Tinyworld Asset Editing

Tiny World Asset Editing

Use the existing board intent contract:

• world[x][z] is intent and cellMeshes['x,z'] is render state.

• New asset edits must flow through setCell(x, z, opts) or helpers that call it.

• Selection state is exposed through window.__tinyworldSelection; use worldCoords(), materialize(), and replaceWorldCoords(). Do not parse raw selectedCells keys in new code.

• Select-tool dragging of an already-selected cell/object should be preview-first: clone the current rendered object/extras into a separate hologram group, update only that virtual offset during pointermove, and commit the real cut/paste once on pointerup. Do not call shiftSelectedCellIntent() repeatedly from pointermove, because intermediate cut/paste steps can wipe cells along the drag path.

• The dedicated Build Brush dock is intentionally top-centered under the world selector/top chrome, not near the bottom toolbar, so users can find it before painting.

• Brush shape modes should keep the same safety contract: Single may use the existing live freehand draw path, but Line/Rectangle/Fill/Scatter must render a holographic footprint first and commit through applyToolToCell() only on pointer-up. Fill previews a bounded flood fill of matching connected cells; Scatter previews a deterministic organic subset inside the dragged rectangle. Keep the current brush mode in window.__tinyworldBrushModes so the mode indicator and UI stay in sync. Non-single brush modes should still feel like paint: selecting one from Select/Island/non-drawable tools (and pressing the canvas while one is active) must switch to a safe drawable fallback, the brush pointer path must win over editable-island widgets and orbit fallback, the ground footprint should update during pointermove before the drag threshold, and release should apply the paint without requiring a second click.

• Duplicate, paste, and latest-template placement should be preview-first: copy/normalize the payload into a pending placement state, show a holographic representation following hover (clone live meshes when available; otherwise use a lightweight clipboard footprint), and commit only on the next board click. Keep Escape as a cancel path and keep any immediate helper explicitly opt-in/fallback-only.

• Radial color changes should be preview-first: swatches should arm a tinted hologram for the selected object/cells and commit through updateSelectedBoardObjects() only on the next board click; Escape cancels.

• Radial Generate should be contextual: summarize the current selection/selected object into the generator prompt/status instead of opening a blank generic modal. Do not imply a scoped apply unless the generator actually supports one; phrase it as context for the preview.

• Generate should be preview-first: after the model returns validated world JSON, stage it as a holographic diff overlay with Apply / Regenerate / Discard controls. Do not call applyState() until the user applies the preview; discard must dispose preview geometries/materials.

• Selected-cell rotation should be preview-first too: radial/keyboard rotate arms a holographic rotated clone, commits the real sel.rotate() on the next board click, and cancels with Escape. Keep immediate rotation as an explicit fallback only.

Contextual selected-object menus:

• The selected-object popup is engine/world/33-radial-menu.js; prefer extending that radial menu over adding a second floating menu for object actions.
• Radial actions should reuse existing edit helpers (duplicateActiveCellIntent(), deleteActiveCellIntent(), openGenerateModal(), selection API methods) rather than writing directly to world.
• Keep destructive actions visually separated with data-pos-type="danger"; keep generation/AI actions on tertiary/orange styling so users can distinguish “create” from “mutate/delete”.

Placement rules:

• Bulk placement over a selection should call the normal applyTool() path once per selected world coord with { skipSelectionBulk: true }. This preserves tool variants, terrain overrides, ghost transforms, fence logic, model stamp settings, and existing setCell side effects.
• Bulk placement with a saved asset template should paste a one-shot template payload at each selected world coord and leave every placed template cell selected, not just the final paste.
• The selection properties Actions row can expose an Apply tool command; it should reuse the same bulk-placement helper rather than duplicating placement logic.
• Shift-drag rectangle fill with a placement tool should leave the filled region selected so users can immediately adjust properties, move, copy, template, or apply another tool.
• Freehand drawing uses dragMode === 'draw', drawVisitedCells, drawLastWorldCoord, and applyDrawToolToHit(). Drawing should not repeatedly stack terrain, bridges, or same-kind objects while the pointer crosses the same cell.
• Successful freehand placement strokes should replace the active selection with the drawn world coords so the Properties panel, copy/duplicate, and template flows are immediately available for the stroke.
• Freehand fence/wall/boundary drawing should de-dupe by world cell plus resolved fence side, so repeated strokes of the same side no-op but corner strokes can add another side to the tile.
• Fence, wall, and boundary are still kind: 'fence'; use fenceSide plus floors. Wall starts at level 4, boundary at level 5. Drawing a higher-level fence over an existing same-side fence should upgrade to that base level, not silently no-op. This also applies when the fence is stored as an extras entry beside another occupant.
• Interpolated freehand fence/wall/boundary cells should derive auto fenceSide from each draw step direction, not from the final pointer edge copied onto every skipped cell. The fence tool is now a single icon with no variant flyout. The placement hologram previews the auto fenceSide from hover (nearest tile edge), and repeat-clicking the same side levels it up 1→2→3→4→5 (wood → taller → wire → stone wall → steel boundary), so Wall/Boundary are reached by re-clicking rather than separate tool variants. The old fixed-direction variants (north, east, center-x, …) and the Edge/Wall/Boundary type variants were removed; the underlying fenceSide values (n/e/s/w/center-x/center-z) and floors levels are still valid for stored/rendered cells.

Clipboard and templates:

• The asset clipboard shape is { version, origin, size, cells: [{ dx, dz, cell }] }.
• Build clipboard cells with cloneCellIntent() so terrain, terrain height, kind, floors, building type, fence side, extras, rotation, offsetX/Y/Z, appearance, and waterFlow survive copy/paste and saved templates.
• Template saves live under tinyworld:asset-templates.v1 in localStorage. Keep these world-intent templates separate from model stamps and voxel build stamps.
• Saving a template should build a one-shot clipboard payload from the active selection/hover target and must not overwrite the user's explicit copy/cut clipboard.
• Pasting or duplicating a multi-cell clipboard should call replaceWorldCoords() with placed cells so the pasted region stays selected for immediate follow-up edits.
• Duplicating selected cells should use a one-shot payload and must not overwrite the user's explicit copy/cut clipboard.
• Moving selected cells between board tiles should reuse the clipboard payload shape internally but must not overwrite the user's explicit copy/cut clipboard.
• Select-tool dragging from inside an active selection should move the selected cells cell-by-cell through the same internal move path, preserving selection and leaving the user's explicit copy/cut clipboard untouched.
• Paste actions should target the hovered cell first, then fall back to the selected region origin. Clear stale hover when the pointer leaves the canvas so this fallback remains reachable. The latest-template shortcut should paste a one-shot template payload, not overwrite the user's explicit copy/cut clipboard.
• Saved asset templates should also surface in the Stamps panel under Templates; selecting one should place from its one-shot template payload and preserve the user's explicit copy/cut clipboard.
• Template cards in Stamps should provide a delete control that removes the localStorage entry, refreshes Stamps counts/cards, and clears stale selected-template tool state.
• Saved template names should summarize their copied cell contents so template cards stay readable and searchable without a separate naming dialog.
• Delete/Backspace should clear the active selection or hovered cell without writing to the asset clipboard; keep this separate from cut/copy semantics.
• The selection properties Actions row should expose the same non-clipboard Delete path so mouse users can clear selected assets without using Cut.
• Keyboard tile moves should keep selection behavior consistent with the property panel: Shift+Arrow shifts selected cells through the internal move path without replacing the user's explicit clipboard, while arrows without an active selection keep camera/ghost behavior.

Selection properties:

• Keep selection property controls grouped by durable sections (Edit, Transform, Appearance, Ground) so dense multi-selection actions stay scannable.
• Selection properties must remain available when AI interfaces are disabled (?ai=0 / html.ai-disabled); hide prompt/chat controls, not the selected-object properties surface, and open selected objects directly to Properties so the property rows are visible.
• Split dense edit actions into scannable rows when needed, but keep routing through durable row keys such as selectionAction so behavior remains centralized.
• Section changes should be presentation-only unless the edit contract changes; preserve existing row keys and route behavior through applySelectionProperty().
• Property group tabs are presentation state only (tinyworld:selection-props-active-tab.v1); keep the durable row keys/actions intact underneath tabbed Edit/Transform/Appearance/Ground views.
• Collapsible property sections should persist in tinyworld:selection-props-collapsed.v1; toggling sections must not remove or rename underlying row keys/actions.
• Icon/round-button treatments for rotate, nudge, scale, and history controls should preserve full labels through aria-label/title; the glyph is visual shorthand, not the action contract.
• Use currentValue plus aria-pressed/.active on property chips when a selected value is uniform, and leave mixed selections unpressed.
• Colour rows and preview quick chips should route through bodyColor/topColor for any supported built-in kind, not just buildings. Expand applyAppearanceToObject() material buckets when exposing new colour rows so the world render and selection preview actually change.
• Colour rows should include a Default option that clears only the matching bodyColor/topColor override while preserving materials, style, transform, and the other colour row.
• Selected-object transform reset controls should clear rotation, offsets, object scale, and per-axis scale while preserving non-transform appearance fields like model/voxel stamp IDs, materials, colours, and style.
• Selected-object scale rows should also provide per-scale reset controls that clear only objectScale, scaleX, scaleY, or scaleZ, preserving materials, colours, model IDs, and style.
• Selected-object nudge controls should include a recenter path that clears only offsetX/Y/Z, preserving rotation, scale, materials, colours, model IDs, and style.
• Selected-object material scale controls should offer a reset path that clears only the matching texture-scale key and keeps the chosen texture/material, colours, model IDs, and style intact.
• The in-scene transform gizmo is constrained to selected object transforms: within-tile X/Z offset, lift, Y rotation, and object scale. It should update the same cell fields as the Properties panel and stay undoable as a single drag batch.
• Duplicate islands are board-level transforms, not selected object transforms. The new-island tool should select/create an editable island board and route gizmo movement/rotation to the island group, while normal object transform rows continue to operate on selected cells only.
• Selection overlays on duplicate islands must be drawn in island-local cell axes. When an island is rotated, transform both selected tile centers and edge-strip offsets through the island group instead of offsetting borders in world X/Z.
• The Layers panel is a read-only world hierarchy surface. It should select cells through window.__tinyworldSelection.replaceWorldCoords(), not by mutating selection internals, and should refresh from tinyworld:selection-changed, tinyworld:world-changed, and tinyworld:grid-changed events.
• The radial root X and the Escape key must close by exiting sub-edit when active, then clearing the active selection through window.__tinyworldSelection.clear() / clearSelection(). That clear path must deselect cells, editable-island engines, and whole editable islands (selectEditableIsland(null)), not merely hide the radial DOM.
• Sub-object editing is surfaced through window.__tinyworldSubEdit, not a parallel inspector state. Layers should show part rows from __tinyworldSubEdit.hierarchy(), select them with selectPart(partKey), and refresh from tinyworld:sub-selection-changed. The shared transform gizmo can target __tinyworldSubEdit.selectedGizmoTarget(); use movePart(..., { snap: !shiftKey }), scalePart(), and rotatePart() so keyboard, Properties, and in-scene handles stay consistent.
• Sub-object edit eligibility is centralized in isVoxelSubEditableKind(). Radial menu and Properties must use that helper instead of maintaining separate kind lists. When a supported built-in object enters sub-edit, renderCellObjectImpl() forces the voxel renderer for that active cell so rock/fence/crop/animal/micro voxel objects get real part keys. Entering edit should not auto-explode; explicit Explode remains a user action. A plain canvas click that misses a selectable part exits sub-edit and must not fall through to cell selection or placement on the same click.
• Model stamps should expose All material / All mat scale controls, but Body/Top material controls should be limited to selected asset kinds with known Tiny World material buckets; mixed selections must not write part-material fields onto model stamps.
• Generated voxel-build / customParts objects are editable through the same Layers / Properties appearance rows as built-ins: All material, Body material, Top material, Body/Top colour, and matching material-scale resets. Keep model-stamp excluded from Body/Top material rows, but do not exclude voxel-build.