Add tile mask helper UI for bucket mapping and update tile save flow

- Add 3x3 neighbor grid on /admin/tilemaps/tiles/edit to build clockwise mask codes

- Compute 8-bit and 4-bit mask values and auto-select matching wall bucket by HashSet-style bucket names

- Show live code/bucket hint output for faster tile authoring

- Change tile save redirect to return to /admin/tilemaps/edit for next-tile workflow

- Add BuilderExecutionPlan_Draft.md for VNext execution planning and review
This commit is contained in:
dingo
2026-02-09 14:26:36 -05:00
parent ab8afd4ec1
commit d447e8eea6
3 changed files with 316 additions and 1 deletions
+164
View File
@@ -0,0 +1,164 @@
# Dungeon Builder Execution Plan (Draft)
## Objective
Deliver a stable, content-driven dungeon builder pipeline that:
1. Uses VNext generation rules (BSP + Random Walk + bucket constraints).
2. Produces deterministic results for a given seed/content snapshot.
3. Keeps admin tooling (`/admin/dungeonbuilder`) aligned with runtime output.
4. Scales to higher-tier larger dungeons with multi-boss support.
## Non-Goals (for this phase)
1. Final art polish for room shapes and micro-layout aesthetics.
2. Replacing every legacy generator immediately.
3. Full client-side editor redesign.
## Guardrails
1. No production cutover without side-by-side validation.
2. Keep V3/V2/V1 fallback available until VNext passes acceptance metrics.
3. Persist and log generator decisions for reproducibility/debugging.
## Workstreams
## 1) Runtime Generator Core (VNext)
### Scope
1. Implement/complete `DungeonGeneratorVNext` stages:
- BSP macro partitioning.
- Random walk connectivity overlay.
- Corridor width enforcement (2-4).
- Bucket-constrained floor placement.
- Wall placement via 8-neighbor mask lookup.
2. Tier scaling:
- Increase map size/room budget for tier 6+.
- Allow multi-boss placement tier 6+.
3. Hard constraints:
- At least one boss per dungeon.
- Dungeon clear requires all bosses defeated.
### Deliverables
1. Deterministic VNext map output for fixed seed + snapshot.
2. Generation report object (counts, fallbacks, violations, timings).
3. Validation/repair pass summary included in report.
## 2) Data + Rules Compilation Layer
### Scope
1. Add precompiled runtime snapshot for:
- floor buckets,
- wall buckets/masks,
- adjacency matrix,
- template pools.
2. Ensure no DB reads in inner generation loops.
3. Add snapshot key/versioning (palette id + updated timestamp).
### Deliverables
1. In-memory immutable generator input model.
2. Cache invalidation hooks on admin content updates.
## 3) Admin Builder Validation
### Scope
1. Add `Validate Palette` flow in admin:
- missing refs,
- invalid JSON,
- out-of-bounds points,
- bucket incompatibilities,
- empty mask mappings.
2. Add readable validation report in UI.
3. Add `Compile Snapshot` action (or compile-on-save).
### Deliverables
1. Actionable error list (not silent catches).
2. Pass/fail status required before TestGen runtime execution.
## 4) TestGen Parity
### Scope
1. Make `/admin/dungeonbuilder/testgen` execute real runtime generator path.
2. Add options:
- seed,
- tier,
- palette,
- generator mode (`VNext`, `V3`, `Auto`).
3. Add side-by-side diff summary:
- rooms/corridors/boss count/connectivity.
### Deliverables
1. TestGen output parity with runtime for same inputs.
2. Exportable generation report JSON.
## 5) Runtime Integration + Feature Flag Rollout
### Scope
1. Keep existing fallback chain but add explicit order:
- `VNext -> V3 -> V2 -> V1`.
2. Add config controls:
- global enable,
- per-tier enable,
- forced fallback mode.
3. Add operational metrics:
- gen time,
- failure reason,
- fallback frequency.
### Deliverables
1. Safe progressive rollout path.
2. Quick rollback switch without redeploy.
## 6) Persistence + Restore Consistency
### Scope
1. Ensure restored dungeons preserve correct walkability + visual tile fidelity for generator used.
2. Persist generator identity/version and snapshot id.
3. Remove V1-only restore assumptions for VNext-generated dungeons.
### Deliverables
1. Rejoin/reload parity with original generated state.
## 7) Boss + Closure Rules Validation
### Scope
1. Enforce:
- minimum 1 boss.
- tier 6+ multi-boss possible.
- clear only when all bosses defeated.
2. Respect `BossesRespawnOnReload` behavior (default false).
### Deliverables
1. Automated verification in simulation tests.
## Milestones
1. M1: VNext core generation stable behind flag.
2. M2: Validation + snapshot compiler integrated.
3. M3: TestGen parity complete.
4. M4: Persistence/rejoin consistency complete.
5. M5: Production rollout by tier bands.
## Acceptance Criteria
1. Corridor width always 2-4.
2. 0 invalid floor cardinal adjacency violations after repair pass.
3. Wall mask resolution >= 99.9% (remaining repaired/fallbacked).
4. Deterministic outputs for fixed seed + snapshot.
5. Every dungeon has >=1 boss; tier 6+ supports multi-boss.
6. Clear condition strictly `defeatedBosses == totalBosses`.
7. TestGen and runtime produce equivalent structural output for same inputs.
8. Rejoin/reload does not corrupt visual state or AI state.
## Risks
1. Legacy content missing bucket/mask metadata.
2. Silent parser assumptions in old data causing invalid compiled snapshots.
3. Performance regressions from repair passes if not bounded.
## Mitigations
1. Strict validation with migration tooling for legacy content.
2. Bounded repair attempts + fallback tile families.
3. Runtime metrics and per-stage timing logs.
## Proposed Implementation Order
1. Runtime report + instrumentation first.
2. Finish VNext core constraints and validations.
3. Build snapshot compiler/caching.
4. Wire admin Validate/Compile.
5. Switch TestGen to runtime generator path.
6. Roll out feature flag by tiers.
7. Finish persistence/rejoin parity and de-risk fallback reduction.
## Review Questions
1. Should tier 6+ boss count scale linearly by tier or by map area budget?
2. Do you want strict generation failure on unresolved bucket adjacency, or auto-repair then warn?
3. Should TestGen default mode be `VNext` once validation passes, or remain `Auto`?
4. Do we enforce one template use per entire dungeon only, or per room category?
5. Should we expose runtime generator mode/tier gating in Admin System panel for live toggling?
@@ -132,12 +132,36 @@
<div class="card p-4 space-y-3">
<h3 class="font-semibold text-white">Buckets</h3>
<p class="text-xs text-gray-500">Assign this tile to one or more buckets.</p>
<div class="border border-gray-700 rounded p-3 bg-gray-900/50 space-y-3">
<div class="text-xs text-gray-300 font-semibold">3x3 Neighbor Mask Helper</div>
<p class="text-xs text-gray-500">
Click neighbors to mark <span class="text-green-400">floor (1)</span> or <span class="text-gray-400">empty/wall (0)</span>.
Bit order is N then clockwise (N, NE, E, SE, S, SW, W, NW).
</p>
<div id="maskGrid" class="grid grid-cols-3 gap-1 w-36">
<button type="button" class="mask-cell" data-dir="n">N</button>
<button type="button" class="mask-cell" data-dir="ne">NE</button>
<button type="button" class="mask-cell" data-dir="e">E</button>
<button type="button" class="mask-cell" data-dir="nw">NW</button>
<div class="mask-center">Tile</div>
<button type="button" class="mask-cell" data-dir="se">SE</button>
<button type="button" class="mask-cell" data-dir="w">W</button>
<button type="button" class="mask-cell" data-dir="sw">SW</button>
<button type="button" class="mask-cell" data-dir="s">S</button>
</div>
<div class="text-xs text-gray-400 space-y-1">
<div>8-bit: <span id="maskCode8" class="text-cyan-300">00000000 (0)</span></div>
<div>4-bit (N,E,S,W): <span id="maskCode4" class="text-cyan-300">0000 (0)</span></div>
<div>Suggested Bucket: <span id="maskBucketHint" class="text-yellow-300">None</span></div>
</div>
</div>
<input type="text" id="bucketFilter" class="input w-full text-sm" placeholder="Type to filter buckets..." oninput="filterBuckets()" />
<div id="bucketList" class="max-h-80 overflow-auto border border-gray-700 rounded p-2 space-y-1">
@foreach (var b in Model.AllBuckets)
{
<label class="flex items-center gap-2 text-sm text-gray-300 bucket-item" data-name="@b.Name.ToLower()">
<input type="checkbox" name="bucketIds" value="@b.Id" class="rounded"
data-bucket-name="@b.Name"
@(Model.SelectedBucketIds.Contains(b.Id) ? "checked" : "") />
<span>@b.Name</span>
@if (!string.IsNullOrWhiteSpace(b.BucketType))
@@ -170,5 +194,132 @@ function filterBuckets() {
el.style.display = el.dataset.name.includes(q) ? '' : 'none';
});
}
const wallBucketSets = [
{ name: "WallInnerCornerDownLeft", mode: 8, codes: [241,224,240,225,160,81,209,97,208,113,17,177,161,144,49,176,33,145] },
{ name: "WallInnerCornerDownRight", mode: 8, codes: [199,195,131,135,130,69,197,67,133,71,68,198,194,132,70,134,196,66] },
{ name: "WallDiagonalCornerDownLeft", mode: 8, codes: [64] },
{ name: "WallDiagonalCornerDownRight", mode: 8, codes: [1] },
{ name: "WallDiagonalCornerUpLeft", mode: 8, codes: [16,80] },
{ name: "WallDiagonalCornerUpRight", mode: 8, codes: [4,5] },
{ name: "WallFullEightDirections", mode: 8, codes: [20,228,147,116,23,22,52,21,84,18,36,19,100,151,244,150,180,229,211,245,215,117,87,101,83,82,37,53,86,213,212,149] },
{ name: "WallTop", mode: 4, codes: [15,6,3,2,10,12,14,11,7] },
{ name: "WallSideLeft", mode: 4, codes: [4] },
{ name: "WallSideRight", mode: 4, codes: [1] },
{ name: "WallBottom", mode: 4, codes: [8] },
{ name: "WallBottm", mode: 4, codes: [8] },
{ name: "WallFull", mode: 4, codes: [13,5,9] }
];
const maskState = { n:0, ne:0, e:0, se:0, s:0, sw:0, w:0, nw:0 };
const bitOrder = ["n","ne","e","se","s","sw","w","nw"];
const cardinalOrder = ["n","e","s","w"];
function normalizeBucketName(name) {
return (name || "").toLowerCase().replace(/[^a-z0-9]/g, "");
}
function computeMaskCode(order) {
let value = 0;
for (let i = 0; i < order.length; i++) {
const bit = maskState[order[i]] ? 1 : 0;
value |= (bit << (order.length - 1 - i));
}
return value;
}
function updateMaskCellVisual(btn, active) {
btn.classList.toggle("mask-on", !!active);
btn.classList.toggle("mask-off", !active);
}
function findMatchingBucketName(code8, code4) {
const match = wallBucketSets.find(set => {
const value = set.mode === 8 ? code8 : code4;
return set.codes.includes(value);
});
return match ? match.name : null;
}
function applyBucketSelection(bucketName) {
const normalizedTarget = normalizeBucketName(bucketName);
const checkboxes = Array.from(document.querySelectorAll('input[name="bucketIds"]'));
if (!normalizedTarget) return;
let matched = false;
for (const cb of checkboxes) {
const n = normalizeBucketName(cb.dataset.bucketName || "");
if (n === normalizedTarget) {
cb.checked = true;
matched = true;
break;
}
}
return matched;
}
function renderMaskSummary() {
const code8 = computeMaskCode(bitOrder);
const code4 = computeMaskCode(cardinalOrder);
const bin8 = code8.toString(2).padStart(8, "0");
const bin4 = code4.toString(2).padStart(4, "0");
document.getElementById("maskCode8").textContent = `${bin8} (${code8})`;
document.getElementById("maskCode4").textContent = `${bin4} (${code4})`;
const bucketName = findMatchingBucketName(code8, code4);
const hint = document.getElementById("maskBucketHint");
if (!bucketName) {
hint.textContent = "None";
return;
}
const applied = applyBucketSelection(bucketName);
hint.textContent = applied ? `${bucketName} (selected)` : `${bucketName} (no matching bucket found by name)`;
}
document.querySelectorAll(".mask-cell").forEach(btn => {
updateMaskCellVisual(btn, false);
btn.addEventListener("click", () => {
const dir = btn.dataset.dir;
maskState[dir] = maskState[dir] ? 0 : 1;
updateMaskCellVisual(btn, maskState[dir]);
renderMaskSummary();
});
});
renderMaskSummary();
</script>
<style>
.mask-cell {
width: 44px;
height: 44px;
border: 1px solid #4b5563;
border-radius: 6px;
font-size: 11px;
color: #d1d5db;
background: #111827;
}
.mask-center {
width: 44px;
height: 44px;
border: 1px solid #4b5563;
border-radius: 6px;
display: flex;
align-items: center;
justify-content: center;
font-size: 10px;
color: #f3f4f6;
background: #1f2937;
}
.mask-on {
background: #14532d;
border-color: #22c55e;
color: #bbf7d0;
}
.mask-off {
background: #111827;
border-color: #4b5563;
color: #d1d5db;
}
</style>
}
@@ -158,7 +158,7 @@ public class TileEditModel : AdminPageModel
await _db.SaveChangesAsync();
return RedirectToPage(new { id = tileId });
return RedirectToPage("/TileMaps/Edit", new { id = Tile.TileMapSheetId });
}
private string NormalizeCdnBaseUrl(string? baseUrl)