日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

2D / 2.5D world authoring studio with peer export lanes for AI RPG Engine, Unreal Engine 5, and Godot 4.
One editor, many modes — paint zones, place entities, define districts, export a complete content pack for your engine of choice.

v4.4.2 — 2155 tests + 6 e2e browser checks, 6 shipping packages, 7 authoring modes, 2.5D authoring, three export targets (AI RPG Engine, Unreal Engine 5, Godot 4)

Architecture

packages/
  schema/          @world-forge/schema         — spatial types, validation, 2.5D fields
  export-ai-rpg/   @world-forge/export-ai-rpg  — AI RPG Engine export pipeline + CLI
  export-unreal/   @world-forge/export-unreal  — Unreal Engine 5 export pipeline + CLI (2.5D aware)
  export-godot/    @world-forge/export-godot   — Godot 4 export pipeline + .tscn scene generation
  renderer-2d/     @world-forge/renderer-2d    — PixiJS 2D canvas renderer
  editor/          @world-forge/editor         — React web authoring app

Quick Start

npm install
npm run build
npm run dev --workspace=packages/editor

Open http://localhost:5173 to launch the editor.

Editor Workflow

1. Choose a mode — dungeon, district, world, ocean, space, interior, or wilderness — to set grid defaults and connection vocabulary
2. Start from a kit — pick a starter kit or genre template from the Template Manager, or start blank
3. Paint zones — drag on the canvas to create zones, connect them, assign districts
4. Place entities — drop NPCs, enemies, merchants, encounters, and items onto zones
5. Review — open the Review tab for health status, content overview, and summary export (Markdown/JSON)
6. Export — open the Export modal to see per-target readiness (✓ Ready / ⚠ advisories), configure target options, then download AI RPG Engine, UE5, or Godot 4 packs. Post-export receipts stack with size, counts, and fidelity details. Also: project bundles (.wfproject.json) and review summaries

CLI Export

# AI RPG Engine
npx world-forge-export project.json --out ./my-pack
npx world-forge-export project.json --validate-only

# Unreal Engine 5
npx world-forge-export-unreal project.json --out ./UnrealPack --sign
npx world-forge-export-unreal --summary ./UnrealPack

Packages

@world-forge/schema

Core TypeScript types and validation for world authoring.

• Spatial types — WorldMap, Zone, ZoneConnection, District, Landmark, SpawnPoint, EncounterAnchor, FactionPresence, PressureHotspot
• Content types — EntityPlacement, ItemPlacement, DialogueDefinition, PlayerTemplate, BuildCatalogDefinition, ProgressionTreeDefinition
• Visual layers — AssetEntry, AssetPack, Tileset, TileLayer, PropDefinition, AmbientLayer
• Mode system — AuthoringMode (7 modes), mode-specific grid/connection/validation profiles
• Validation — validateProject() (60+ structural checks with Map-based O(n) lookups, warningCount), advisoryValidation() (mode-specific suggestions, metadata completeness, asset naming)
• Utilities — assembleSceneData() (visual bindings with missing-asset detection), scanDependencies() (reference graph analysis), buildReviewSnapshot() (health classification)

@world-forge/export-unreal

Converts a WorldProject into an Unreal Engine 5 content pack tuned for 2.5D games.

• Output — pack.json, per-zone and per-district Primary Data Asset JSON, grouped actor spawn manifest, level-streaming hints per connection, World Partition cell hints, and a structured fidelity report.
• 2.5D fields — Zone.elevation, elevationRange, parallaxLayers, skylineRef are preserved and converted into UE cm / Z-up coordinates.
• Coordinate transform — pure functions (pixelsToUnrealCm, elevationToZ, worldForgeToUnrealAxis, gridToUnrealAxis). Default world scale is 1 tile = 100 cm.
• Round-trip import — importFromUnreal reconstructs a WorldProject from an Unreal pack; gameplay-only data (dialogues, progression, builds) is flagged as dropped in the fidelity report.
• CLI — world-forge-export-unreal with --out, --tile-size-cm, --validate-only, --verbose.

@world-forge/export-godot

Converts a WorldProject into a Godot 4 content pack with .tscn scene text.

• Output — pack.json, per-zone resources, entity manifest, navigation links, loot tables, spawn markers, transition nodes, dialogue resources, asset bindings, and a world .tscn scene
• Scene generation — buildWorldScene() produces Godot scene text via the .tres serializer
• Coordinate transform — World Forge grid → Godot 2D coordinates
• Fidelity reporting — structured tracking of lossless, approximated, and dropped data
• Format version — GODOT_PACK_FORMAT_VERSION 1.0.0

@world-forge/export-ai-rpg

Converts a WorldProject into ai-rpg-engine's ContentPack format.

• Export — zones, districts, entities, items, dialogues, player template, build catalog, progression trees, encounters, factions, hotspots, manifest, and pack metadata
• Import — 8 reverse converters reconstruct a WorldProject from exported JSON
• Fidelity reporting — structured tracking of what was lossless, approximated, or dropped during conversion
• Format detection — auto-detects WorldProject, ExportResult, ContentPack, and ProjectBundle formats
• CLI — world-forge-export command with --out, --validate-only, and --verbose flags

@world-forge/renderer-2d

PixiJS-based 2D renderer: viewport with pan/zoom, zone overlays with district coloring, connection arrows, entity icons by role, tile layers, and a minimap.

@world-forge/editor

React 19 + Vite web app with Zustand state management, undo/redo with action labels, auto-save (30s throttle, 3-version history, crash recovery), dirty-state guards on all project-loading paths, dark/light theme toggle, modal focus traps, and keyboard-driven tool switching.

Workspace Tabs

Tab	Purpose
Map	Zone/entity/district editing on the 2D canvas
Objects	Hierarchical tree: districts → zones → entities/landmarks/spawns
Player	Player template with stats, inventory, equipment, spawn
Builds	Archetypes, backgrounds, traits, disciplines, combos
Trees	Progression nodes with requirements and effects
Dialogue	Node editing, choice linking, broken-ref detection
Presets	Region and encounter preset browser with merge/overwrite
Assets	Asset library with kind-filtered search, orphan detection, asset packs
Issues	Live grouped validation with click-to-focus navigation
Deps	Dependency scanner with inline repair buttons
Review	Health dashboard, content overview, summary export
Guide	First-run checklist with hotkey reference

Canvas & Editing

• Tools — select, zone-paint, connection, entity-place, landmark, spawn
• Multi-select — shift-click, box-select, Ctrl+A; drag-move with atomic undo
• Alignment — 6-way align (left/right/top/bottom/center-h/center-v) and horizontal/vertical distribution
• Snapping — drag-time snap to edges/centers of nearby objects with visual guide lines
• Resize — 8 handles per zone with edge snapping, min-size clamping, live preview
• Duplicate — Ctrl+D with remapped IDs, connections, and district assignments
• Copy/Paste — Ctrl+C / Ctrl+V with ID remapping and configurable offset
• Click-cycle — repeated clicks at same position cycle through overlapping objects
• Context menu — right-click for 7 context-sensitive actions (properties, delete, duplicate, etc.)
• Connection preview — dashed cyan line during connection tool placement
• Minimap — 200×150 overview (bottom-right), click to jump
• Viewport culling — only renders objects within visible bounds (64px margin)
• Performance stats — toggle FPS/object count/render time overlay
• Per-object visibility — hide/show individual objects (persisted in localStorage)
• Layers — 7 visibility toggles (grid, connections, entities, landmarks, spawns, backgrounds, ambient)

Navigation & Shortcuts

• Viewport — pan/zoom camera, mousewheel zoom (cursor-anchored), spacebar/middle-mouse/right-click drag-pan, auto fit-to-content, double-click to center
• Search — Ctrl+K opens overlay to find any object by name/ID with fuzzy matching, keyboard navigation, and recent search history (localStorage)
• Speed Panel — double-right-click for a floating command palette with context-aware actions, pinnable favorites, macros, and mode-suggested quick actions
• Hotkeys — 21 keyboard shortcuts including tool switching (V/Z/C/E/L/S), Enter (open details), P (apply preset), Shift+P (save preset), Ctrl+C/V (copy/paste), arrow nudge (Shift = 5×)
• Accessibility — modal focus traps with Escape-to-close, ARIA labels on all icon-only buttons, keyboard-navigable object tree, screen-reader-announced dirty indicator. Spatial canvas operations (placement, box-select, resize, connection drawing, panning) remain pointer-based

Import & Export

• ContentPack — target-aware export to AI RPG Engine, Unreal Engine 5, or Godot 4 with per-target readiness badges, configurable options (tile size, scene prefixes, bundle filtering), and post-download receipts
• Project bundles — portable .wfproject.json files with provenance metadata and dependency info
• Kit bundles — .wfkit.json export/import with validation, collision handling, and provenance tracking
• Import — auto-detects 4 formats with structured fidelity reporting
• Diff — semantic change tracking since import
• Scene preview — inline HTML/CSS composition of all zone visual bindings

Authoring Modes

World Forge separates genre (fantasy, cyberpunk, pirate) from mode (dungeon, ocean, space). Genre is flavor — mode is scale. Mode governs grid defaults, connection vocabulary, validation suggestions, guide wording, and preset filtering.

Mode	Grid	Tile	Key Connections
Dungeon	30×25	32	door, stairs, passage, secret, hazard
District / City	50×40	32	road, door, passage, portal
Region / World	80×60	48	road, portal, passage
Ocean / Sea	60×50	48	channel, route, portal, hazard
Space	100×80	64	docking, warp, passage, portal
Interior	20×15	24	door, stairs, passage, secret
Wilderness	60×50	48	trail, road, passage, hazard

Mode is set when creating a project and stored as mode?: AuthoringMode on WorldProject. Each mode provides smart defaults — connection kinds, entity roles, zone names, and Speed Panel suggestions adapt automatically.

Authoring Surface

World Structure

• Zones with spatial layout, neighbors, exits, light, noise, hazards, and interactables
• 12 connection kinds (passage, door, stairs, road, portal, secret, hazard, channel, route, docking, warp, trail) with distinct visual styles, edge-anchored routing, directional arrowheads, and conditional dashed styling
• Districts with faction control, economy profiles, metrics sliders, tags, and district name labels at zone centroids
• Landmarks (named points of interest within zones)
• Spawn points, encounter anchors (type-based coloring), faction presences, and pressure hotspots

Content

• Entity placements with stats, resources, AI profiles, and custom metadata
• Item placements with slot, rarity, stat modifiers, and granted verbs
• Dialogue trees with branching conversations, conditions, and effects
• Encounter anchors on canvas — red diamond markers with boss/ambush/patrol types

Character Systems

• Player template (starting stats, inventory, equipment, spawn point)
• Build catalog (archetypes, backgrounds, traits, disciplines, cross-titles, entanglements)
• Progression trees (skill/ability nodes with requirements and effects)

Assets

• Asset manifest (portraits, sprites, backgrounds, icons, tilesets) with kind-specific bindings
• Asset packs (named, versioned groupings with compatibility metadata, theme, license)
• Scene preview (inline composition of all zone visual bindings with missing-asset detection)

Workflow

• Region presets (9 built-in, mode-filtered) and encounter presets (10 built-in) with merge/overwrite application and custom preset CRUD
• Starter kits (7 built-in, mode-specific) with kit export/import (.wfkit.json), collision handling, and provenance tracking
• Layout templates (6 prebuilt zone arrangements) and dialogue templates (5 conversation starters)
• Zone merge and batch entity placement (grid/random/circle patterns)
• Auto-save with 30-second throttle and 3-version recovery history
• Ctrl+K search across all object types with fuzzy matching and recent history
• Speed Panel command palette with pinnable favorites, macros, custom groups, and mode suggestions
• 21 centralized keyboard shortcuts (including 6 tool-switching keys)
• Project metadata editor (author, license, category, tags)
• Review statistics (role distribution, connection kinds, encounter types, zones per district)
• Export to ContentPack JSON, project bundles, and review summaries
• Import from 4 formats with structured fidelity reporting, repair suggestions, and semantic diff tracking

See dogfood/WALKTHROUGH.md for the Chapel Threshold export handshake proving the current surface.

Dogfood Directory

The dogfood/ directory contains an integration test harness that exercises the full authoring-to-export pipeline outside of unit tests. The Chapel Threshold example (chapel-threshold.ts) builds a small but complete world project, runs it through export, and writes the output to dogfood/output/. This proves that schema types, validation, and the export pipeline work end-to-end with real data — not just isolated mocks.

Engine Compatibility

Exports target three engines:

• ai-rpg-engine — ContentPack format, loadable by claude-rpg
• Unreal Engine 5 — 2.5D-aware content pack with Primary Data Assets, actor spawn manifests, and World Partition hints
• Godot 4 — .tscn scene generation with zone resources, navigation links, and entity manifests

Security

• Data touched: project files on local disk (user-created JSON), no server-side storage
• Data NOT touched: no telemetry, no analytics, no network requests beyond local dev server
• Permissions: no API keys, no secrets, no credentials
• No secrets, tokens, or credentials in source

License

MIT

---

Built by MCP Tool Shop