Expand request review tooling and KB
This commit is contained in:
parent
ab1dfbf029
commit
cae21b61b7
16 changed files with 1258 additions and 241 deletions
|
|
@ -1,48 +1,47 @@
|
|||
# Chunk Storage And Streaming
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
World data is stored as per-chunk JSON files and loaded into the editor as chunk neighborhoods around a center chunk. The runtime caches chunk payloads, shifts neighborhoods as the viewport moves, and saves dirty chunks in batches.
|
||||
This system owns the world-mode chunk model: loading chunk neighborhoods, composing chunk data into the current editor session, and persisting chunk updates back to disk.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- Load a neighborhood of chunks around a world position.
|
||||
- Compose room layers from chunk-local rows into a temporary larger editing surface.
|
||||
- Compose sparse height layers from chunk data.
|
||||
- Compose placed instances and overlays from chunk payloads.
|
||||
- Batch-save chunk changes back to the API.
|
||||
|
||||
## Important Data
|
||||
|
||||
Chunk payloads can contribute:
|
||||
|
||||
- `roomLayers`
|
||||
- `heightLayers`
|
||||
- `instances`
|
||||
- `backgroundTileId`
|
||||
- chunk coordinates and dimensions
|
||||
|
||||
## Important Files
|
||||
|
||||
- `server.js`
|
||||
- `src/worldChunking.ts`
|
||||
- `src/worldshaperStudio/bootstrap.ts`
|
||||
- `src/worldshaperStudio/runtime.ts`
|
||||
- `src/worldshaperStudio/persistenceController.ts`
|
||||
|
||||
## Endpoints It Uses
|
||||
## Known Behavior Notes
|
||||
|
||||
- `GET /api/world/:worldId/chunk/:chunkX/:chunkY`
|
||||
- `POST /api/world/:worldId/chunk/:chunkX/:chunkY`
|
||||
- `GET /api/world/:worldId/chunks`
|
||||
- `POST /api/world/:worldId/chunks/batch-save`
|
||||
- The bootstrap path currently loads a neighborhood around an initial bookmark or world center instead of streaming every chunk in the world.
|
||||
- Exact chunk access is grid-based, so many performance requests should start with profiling the current neighborhood/cache path before proposing spatial trees.
|
||||
- World mode is not editing one isolated chunk in a vacuum; it edits a composed surface backed by many chunk records.
|
||||
|
||||
## Important Data And Rules
|
||||
## Relationships
|
||||
|
||||
- chunks are stored as `content/worlds/<worldId>/chunks/<x>_<y>.json`
|
||||
- world neighborhoods are requested as a square around a center chunk
|
||||
- runtime keeps a chunk cache and tracks dirty chunk keys
|
||||
- chunk payloads include `roomLayers`, `heightLayers`, `instances`, and optional `backgroundTileId`
|
||||
- Feeds `Layers And Tile Editing`, which paints onto the composed chunk neighborhood.
|
||||
- Feeds `World Overview`, which visualizes and transforms chunk-level records.
|
||||
- Depends on `Persistence And Save Pipeline` to write chunk mutations.
|
||||
- Feeds `Rendering And Viewport`, which only draws what the currently loaded chunk neighborhood exposes.
|
||||
|
||||
## Invariants And Constraints
|
||||
## Triage Hints
|
||||
|
||||
- Exact chunk lookup is grid-based and direct.
|
||||
- The editor does not load the entire world for normal editing.
|
||||
- Small tile edits must sync back into the correct cached chunk.
|
||||
- Save flow should preserve chunk-local edits without rebuilding unrelated chunks.
|
||||
|
||||
## Common Request Themes
|
||||
|
||||
- chunk loading speed
|
||||
- chunk streaming behavior
|
||||
- per-chunk backgrounds
|
||||
- chunk transforms, duplication, deletion
|
||||
- performance questions around indexing and caching
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is the request about storage, fetch patterns, cache behavior, or save behavior?
|
||||
- Does it affect only visible chunks or the full world?
|
||||
- Is the user asking for chunk-local data, or freeform world overlays that break chunk assumptions?
|
||||
Requests about chunk loading, chunk transforms, chunk duplication, world streaming, chunk persistence, spatial indexing, and neighborhood performance should start here.
|
||||
|
|
|
|||
|
|
@ -1,48 +1,55 @@
|
|||
# Graphics Painter
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
The Graphics Painter is the tile and sprite art editing window. It handles pixel editing, frame management, animation timeline editing, preview playback, and import-oriented art workflows.
|
||||
This is the dedicated art-editing environment for tile and sprite graphics. It covers shape tools, erasers, transforms, previewing, and animation timeline editing for the currently opened asset.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- Shape drawing modes:
|
||||
- rectangle
|
||||
- circle
|
||||
- triangle
|
||||
- line
|
||||
- Shape variants:
|
||||
- outline
|
||||
- fill
|
||||
- outline + fill
|
||||
- Shape erasers:
|
||||
- rectangle
|
||||
- circle
|
||||
- triangle
|
||||
- Transform workflows available through the painter menu.
|
||||
- Animation timeline controls, frame order, playback speed, and preview.
|
||||
|
||||
## Important UI Surfaces
|
||||
|
||||
- Graphic Painter window
|
||||
- Tool menu and tooltip menus
|
||||
- Animation timeline row
|
||||
- Preview card and frame preview
|
||||
|
||||
## Important Files
|
||||
|
||||
- `src/worldshaperStudio/tileArtEditorWindowController.ts`
|
||||
- `src/worldshaperStudio/graphicsDocumentHelpers.ts`
|
||||
- `src/worldshaperStudio/importController.ts`
|
||||
- `src/worldshaperStudio/dom.ts`
|
||||
|
||||
## Endpoints It Uses
|
||||
## Known Tool Details
|
||||
|
||||
- `GET /api/images`
|
||||
- `GET /api/images/:filename`
|
||||
- `POST /api/content/images`
|
||||
- `POST /api/content/sprites`
|
||||
- `POST /api/content/tiles`
|
||||
- Shape menus are nested by shape and variant, rather than being a single flat tool list.
|
||||
- The active draw tool and active eraser shape are tracked separately.
|
||||
- The painter already knows about animation preview, frame creation, and per-frame editing; many animation requests should be phrased as extensions to an existing timeline rather than brand-new systems.
|
||||
- The preview and animation controls are editor-side only; runtime rendering requests often cross into `Rendering And Viewport`.
|
||||
|
||||
## Important Data And Rules
|
||||
## Relationships
|
||||
|
||||
- graphics records may include animation frame data and playback metadata
|
||||
- preview behavior is maintained in painter-local UI state
|
||||
- art changes eventually flow into tile and sprite content records
|
||||
- imports and previews are tightly tied to painter usability
|
||||
- Depends on `Content Catalog And Records` for source records and saved asset definitions.
|
||||
- Depends on `Floating Window Shell` because the painter lives inside a movable editor window.
|
||||
- Feeds `Rendering And Viewport` when edited assets are later shown in the live map renderer.
|
||||
- Intersects with `Animation`-tagged requests when frame behavior changes.
|
||||
|
||||
## Invariants And Constraints
|
||||
## Triage Hints
|
||||
|
||||
- the painter is a floating tool window, not a docked pane
|
||||
- animation preview should reflect current frame ordering and speed settings
|
||||
- save behavior must preserve frame structure and timing metadata
|
||||
- painter workflows often depend on tile and sprite schema conventions
|
||||
|
||||
## Common Request Themes
|
||||
|
||||
- move or selection tools
|
||||
- frame duplication and frame management
|
||||
- animation controls
|
||||
- import workflow improvements
|
||||
- better preview behavior
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is this request about art authoring, record storage, or runtime playback?
|
||||
- Does it affect tiles, sprites, or both?
|
||||
- Is the requested behavior inside the painter window only?
|
||||
Requests about sprite drawing, tile art tools, frame duplication, painter transforms, selection or move workflows, and editor-side animation controls should usually start here.
|
||||
|
|
|
|||
|
|
@ -1,42 +1,36 @@
|
|||
# Launcher Home
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
The launcher is the public-facing entry point for Worldshaper. It presents the hero card, opens the editor in its own floating window, links to the repo, and hosts the News and Requests tabs.
|
||||
The launcher is the public-facing web shell for Worldshaper. It handles editor launch, launch presentation, release notes, repo navigation, and the visible request board entry point.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- Open the editor in a separate floating window.
|
||||
- Show the release/news presentation.
|
||||
- Show the Requests board.
|
||||
- Swap between public request browsing and protected admin review mode.
|
||||
- Present launcher artwork and page-level theming.
|
||||
|
||||
## Important Files
|
||||
|
||||
- `src/WorldshaperLauncher.tsx`
|
||||
- `src/index.css`
|
||||
- `src/worldshaperStudio/windowing.ts`
|
||||
|
||||
## Endpoints It Uses
|
||||
## Important UI Surfaces
|
||||
|
||||
- `GET /api/world-default`
|
||||
- `GET /api/launcher-requests`
|
||||
- Hero launch card
|
||||
- News tab
|
||||
- Requests tab
|
||||
- Protected admin unlock flow
|
||||
|
||||
## Important State
|
||||
## Relationships
|
||||
|
||||
- launch state: ready, opening, opened, blocked, error
|
||||
- active board tab: news or requests
|
||||
- request list, filters, and expanded request rows
|
||||
- resolved default world id
|
||||
- Depends on `Floating Window Shell` for popup launch behavior.
|
||||
- Depends on `Request Board` for request intake and moderation UI.
|
||||
- Intersects with `Website` and `Polish` requests more than the editor-runtime systems do.
|
||||
|
||||
## Invariants And Constraints
|
||||
## Triage Hints
|
||||
|
||||
- The editor is intended to open in a separate popup-style window.
|
||||
- The launcher should still work if the default world lookup fails by falling back to `overworld`.
|
||||
- Browser popup blocking is a real failure mode and must be surfaced to the user.
|
||||
|
||||
## Common Request Themes
|
||||
|
||||
- page styling and presentation
|
||||
- launch flow and popup behavior
|
||||
- repo button or external links
|
||||
- tab layout and launcher information architecture
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is this about the launcher page itself, or the studio window after launch?
|
||||
- Does it affect only presentation, or also request API behavior?
|
||||
- Does it depend on popup/window behavior?
|
||||
Requests about the landing page, launch flow, background presentation, release content, public request visibility, and repo-linking should start here.
|
||||
|
|
|
|||
|
|
@ -1,47 +1,55 @@
|
|||
# Layers And Tile Editing
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
This subsystem handles normal tile painting, erasing, selection, visible layer management, sparse height layers, and the mapping between visible document edits and stored chunk data.
|
||||
This system owns the main world-canvas tile workflow: selecting a room layer, choosing a tile brush, painting, erasing, and editing sparse height layers in world mode.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- Freehand tile painting on the active layer.
|
||||
- Shape strokes for the world canvas:
|
||||
- freehand
|
||||
- rectangle outline
|
||||
- circle outline
|
||||
- line with axis lock behavior
|
||||
- Height-layer painting modes:
|
||||
- single or freehand paint
|
||||
- rectangle fill
|
||||
- circle fill
|
||||
- erase variants for the same shapes
|
||||
- Background-cell editing modes:
|
||||
- explicit tile stamp
|
||||
- transparent hole
|
||||
- inherit world background
|
||||
|
||||
## Important UI Surfaces
|
||||
|
||||
- Layers sidebar
|
||||
- Height layer list
|
||||
- Canvas brush interactions
|
||||
- Background mode button and preview
|
||||
|
||||
## Important Files
|
||||
|
||||
- `src/worldshaperStudio/interactionController.ts`
|
||||
- `src/worldshaperStudio/runtime.ts`
|
||||
- `src/worldshaperStudio/sidebarController.ts`
|
||||
- `src/worldshaperStudio/runtime.ts`
|
||||
- `src/worldshaperStudio/mapDocumentController.ts`
|
||||
- `src/worldshaperStudio/popupSessionStore.ts`
|
||||
- `src/worldshaperStudio/dom.ts`
|
||||
|
||||
## Endpoints It Uses
|
||||
## Known Tool Details
|
||||
|
||||
- primarily saved through `POST /api/world/:worldId/chunks/batch-save`
|
||||
- Tile strokes register history entries with shape-specific labels such as rectangle stroke, circle stroke, brush stroke, and erase stroke.
|
||||
- Height strokes register their own history labels and track the target Z layer.
|
||||
- Layer editing is tightly coupled to the currently loaded chunk neighborhood in world mode.
|
||||
- Brush behavior depends on catalog tile metadata resolved through runtime helpers.
|
||||
|
||||
## Important Data And Rules
|
||||
## Relationships
|
||||
|
||||
- room layer `0` is the base layer
|
||||
- non-base layers use sparse or transparent-style fill semantics
|
||||
- height layers are separate structures from room layers
|
||||
- visibility is tracked in popup session state
|
||||
- painting in world mode must mark affected chunks dirty
|
||||
- Depends on `Content Catalog And Records` for tile definitions and brush metadata.
|
||||
- Depends on `Chunk Storage And Streaming` for the currently editable chunk neighborhood.
|
||||
- Depends on `Persistence And Save Pipeline` for actually writing edits back to storage.
|
||||
- Feeds `Rendering And Viewport`, which visualizes the edited layers and sparse height patches.
|
||||
|
||||
## Invariants And Constraints
|
||||
## Triage Hints
|
||||
|
||||
- layer ordering matters to rendering and selection behavior
|
||||
- layer visibility must not destroy layer data
|
||||
- tile edits in world mode must map local viewport coordinates back to world chunk coordinates
|
||||
- height layers are not the same thing as standard room layers
|
||||
|
||||
## Common Request Themes
|
||||
|
||||
- better layer reordering
|
||||
- more precise tiling tools
|
||||
- height/elevation features
|
||||
- snapping or unsnapped placement
|
||||
- erase or selection behavior
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is this about normal room layers or height layers?
|
||||
- Does the request affect paint semantics, visibility, ordering, or storage?
|
||||
- Does it apply to map mode, world mode, or both?
|
||||
Requests about rectangle tools, brush behavior, height painting, active layer confusion, background stamping, and tile-placement modes should usually start here, even when they also touch rendering or chunk persistence.
|
||||
|
|
|
|||
|
|
@ -1,54 +1,47 @@
|
|||
# Request Board
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
The request board lives on the launcher and stores lightweight user submissions. It currently supports pending and active request states, filtering, expansion of active items, and deletion with confirmation.
|
||||
The request board is the launcher-side intake, queue, moderation, and review surface for product requests. It stores raw submissions, structured analysis, active request rows, and admin-only review actions.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- `src/WorldshaperLauncher.tsx`
|
||||
- `server.js`
|
||||
- `data/launcher_requests.json`
|
||||
- Save public request submissions.
|
||||
- Keep raw source text alongside normalized active requests.
|
||||
- Store structured analysis metadata for pending requests.
|
||||
- Filter by status and standardized tags.
|
||||
- Protect admin review actions behind server-side password checks.
|
||||
- Promote reviewed request items into active request rows.
|
||||
|
||||
## Endpoints It Uses
|
||||
## Important Endpoints
|
||||
|
||||
- `GET /api/launcher-requests`
|
||||
- `POST /api/launcher-requests`
|
||||
- `PATCH /api/launcher-requests/:requestId`
|
||||
- `DELETE /api/launcher-requests/:requestId`
|
||||
- `POST /api/launcher-requests/:requestId/process-analysis`
|
||||
- `POST /api/launcher-requests/process-pending`
|
||||
- `GET /api/launcher-request-meta`
|
||||
- `POST /api/admin/auth-check`
|
||||
|
||||
## Important Data Shape
|
||||
|
||||
Current request records include:
|
||||
Request records can now contain:
|
||||
|
||||
- `id`
|
||||
- `sourceSubmissionId`
|
||||
- `title`
|
||||
- `status`
|
||||
- `category`
|
||||
- `tags`
|
||||
- `sourceText`
|
||||
- `summary`
|
||||
- `implementationNotes`
|
||||
- `createdAt`
|
||||
- `updatedAt`
|
||||
- public fields such as title, category, tags, summary, and implementation notes
|
||||
- raw `sourceText`
|
||||
- `analysis.state`
|
||||
- `analysis.items[]`
|
||||
- per-item review rationale
|
||||
- per-item possible options
|
||||
- structured affected-system and affected-file hints
|
||||
|
||||
## Invariants And Constraints
|
||||
## Relationships
|
||||
|
||||
- New submissions enter as pending unless promoted.
|
||||
- One raw submission may contain multiple real feature requests.
|
||||
- Active requests should be normalized, titled, and tagged.
|
||||
- Deletion is destructive and should remain explicit.
|
||||
- Depends on `Launcher Home` for the public site presentation.
|
||||
- Depends on the KB under `docs/kb/` for model-grounded request parsing.
|
||||
- Depends on the request-analysis worker for automated triage.
|
||||
|
||||
## Common Request Themes
|
||||
## Triage Hints
|
||||
|
||||
- parse and split user submissions
|
||||
- request tags and filtering
|
||||
- moderation and cleanup
|
||||
- queue automation and confidence review
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is the user asking to change request storage, presentation, or parsing behavior?
|
||||
- Should one submission become many active requests?
|
||||
- Is the request really a bug report or a feature idea?
|
||||
Requests about queue automation, moderation, review UI, request splitting, approval workflows, structured tags, and admin tooling should start here.
|
||||
|
|
|
|||
|
|
@ -1,45 +1,44 @@
|
|||
# World Overview
|
||||
|
||||
## What It Does
|
||||
## What It Owns
|
||||
|
||||
World Overview is a separate window that displays a coarse map of all known chunks, supports bookmark navigation, and exposes chunk operations such as move, duplicate, rotate, flip, delete, and background adjustments.
|
||||
The World Overview is the large-scale chunk map used for navigation, chunk inspection, bookmark placement, and chunk-level operations that would be awkward from the tile canvas alone.
|
||||
|
||||
## Key Files
|
||||
## Core Behaviors
|
||||
|
||||
- Navigate directly to a chunk.
|
||||
- Move chunk content.
|
||||
- Duplicate chunk tiles.
|
||||
- Flip and rotate chunk content.
|
||||
- Delete a chunk and clear its tiles, height data, and placed entities.
|
||||
- Paint or restore the chunk background tile.
|
||||
- Create POIs and bookmarks from chunk positions.
|
||||
|
||||
## Important UI Surfaces
|
||||
|
||||
- World Overview floating window
|
||||
- Chunk context menu
|
||||
- Pending chunk-action flow
|
||||
- Bookmark and POI display
|
||||
|
||||
## Important Files
|
||||
|
||||
- `src/worldshaperStudio/worldOverviewWindowController.ts`
|
||||
- `src/worldshaperStudio/dom.ts`
|
||||
- `server.js`
|
||||
|
||||
## Endpoints It Uses
|
||||
## Known Behavior Notes
|
||||
|
||||
- `GET /api/world/:worldId/overview`
|
||||
- `GET /api/world/:worldId/bookmarks`
|
||||
- bookmark writes flow through the world save path
|
||||
- The chunk context menu is already a rich operations hub, so many requests in this area are extensions to an existing menu rather than requests for a brand-new system.
|
||||
- Pending move and duplicate actions are stateful; the overview can wait for a second chunk selection before executing.
|
||||
- The overview also exposes quick background-painting workflows at the chunk level.
|
||||
|
||||
## Important Data And Rules
|
||||
## Relationships
|
||||
|
||||
- overview currently requests the full set of world chunks from the server
|
||||
- it draws its own chunk preview surfaces
|
||||
- it merges server chunks with cached client chunks to reflect unsaved local state
|
||||
- chunk context menus expose world-level operations
|
||||
- Depends on `Chunk Storage And Streaming` for chunk records and chunk dimensions.
|
||||
- Depends on `Windows` because the overview lives in its own floating tool window.
|
||||
- Often intersects with `Layers` and `Tiling` when users want higher-level terrain or chunk painting workflows.
|
||||
|
||||
## Invariants And Constraints
|
||||
## Triage Hints
|
||||
|
||||
- overview is only available in world mode
|
||||
- overview actions should not silently discard unsaved chunk edits
|
||||
- chunk transform actions must preserve chunk addressing rules
|
||||
- the full overview payload can become a performance hotspot on larger worlds
|
||||
|
||||
## Common Request Themes
|
||||
|
||||
- chunk operations
|
||||
- world navigation
|
||||
- bookmark workflows
|
||||
- overview performance
|
||||
- better high-level visualization
|
||||
|
||||
## Triage Questions
|
||||
|
||||
- Is the issue specific to the overview window, or all world editing?
|
||||
- Does it affect overview drawing only, or also chunk save/load behavior?
|
||||
- Is the request about overview scale, navigation, or chunk manipulation?
|
||||
Requests about chunk move, duplicate, rotate, delete, POIs, overview navigation, and world-scale map management should begin here.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue