Worldshaper/README.md

Worldshaper

Canonical React + TypeScript worldbuilding studio and API for Worldshaper Studio.

Features

• Load content types from /api/types.
• Load selected content payload from /api/content/:type.
• Edit raw JSON.
• Save JSON back to /api/content/:type.

Runtime

• Vite dev server runs on http://localhost:4170.
• API/app server runs on http://localhost:5180 from server.js in this folder.
• vite.config.ts proxies /api to http://localhost:5180.
• Override the API/app port with PORT=<port> when needed.

Content Location

• Preferred: place content beside server.js at tools/worldshaper/content/.
• Required image folder for /api/images: tools/worldshaper/content/Images/ (capital I).
• Optional override: set CONTENT_ROOT=/absolute/path/to/content before starting the API.
• Fallbacks remain for legacy layouts, but local tools/worldshaper/content is checked first.

Local development

From this folder:

1. npm install
2. In one terminal: npm run dev:api
3. In another terminal: npm run dev

Build

• npm run build
• npm run clean:workspace removes generated bundles, logs, and disposable local artifacts.

Project Structure

This repo is easiest to manage when the root stays limited to the live app and its source-of-truth assets:

• src/ React, TypeScript, and editor code
• content/ canonical game content, schemas, worlds, and images metadata
• data/ editor metadata and local settings payloads
• scripts/ maintenance, validation, and deployment helpers
• public/ static assets copied by Vite

Generated or disposable folders such as dist/, output/, backups/, and Release/ should not be treated as source-of-truth project files.

Scope guardrails

• Keep files small and modular.
• No cross-file autofix/migration tooling in V2.1.
• Finish core CRUD + validation workflows before adding advanced UX.