Initial commit

docs/item-schema.md

@@ -0,0 +1,118 @@
+# Item Schema
+
+## World Item (server-authoritative)
+
+```json
+{
+  "id": "string",
+  "type": "radio_station | dice",
+  "title": "string",
+  "x": 0,
+  "y": 0,
+  "createdBy": "user-id",
+  "createdAt": 1735689600000,
+  "updatedAt": 1735689600000,
+  "version": 1,
+  "capabilities": ["editable", "carryable", "deletable", "usable"],
+  "useSound": "sounds/roll.ogg",
+  "params": {},
+  "carrierId": null
+}
+```
+
+- `useSound`: optional client-played sound path when item `use` succeeds; global item field and not user-editable in V1.
+- `capabilities` and `useSound` are derived from global item-type definitions at runtime (not stored per-instance in persisted state).
+
+## Persisted Item State (`server/runtime/items.json`)
+
+```json
+{
+  "id": "string",
+  "type": "radio_station | dice",
+  "title": "string",
+  "x": 0,
+  "y": 0,
+  "createdBy": "user-id",
+  "createdAt": 1735689600000,
+  "updatedAt": 1735689600000,
+  "version": 1,
+  "params": {},
+  "carrierId": null
+}
+```
+
+- Persisted state stores only instance data.
+- Global/type-level properties are loaded from server registry in `server/app/item_catalog.py`.
+
+## Type Params
+
+### `radio_station`
+
+```json
+{
+  "streamUrl": "",
+  "enabled": true,
+  "volume": 50
+}
+```
+
+- `streamUrl`: string, empty allowed until configured.
+- `enabled`: boolean on/off flag.
+  - UI behavior: in property menu, `Enter` toggles on/off directly.
+- `volume`: integer, range `0-100`, default `50`.
+
+### `dice`
+
+```json
+{
+  "sides": 6,
+  "number": 2
+}
+```
+
+- `sides`: integer, range `1-100`.
+- `number`: integer, range `1-100`.
+
+## Packet Shapes
+
+- `item_upsert`:
+
+```json
+{
+  "type": "item_upsert",
+  "item": { "..." : "World Item" }
+}
+```
+
+- `item_remove`:
+
+```json
+{
+  "type": "item_remove",
+  "itemId": "item-id"
+}
+```
+
+- `item_action_result`:
+
+```json
+{
+  "type": "item_action_result",
+  "ok": true,
+  "action": "add | pickup | drop | delete | use | update",
+  "message": "human-readable status",
+  "itemId": "optional-item-id"
+}
+```
+
+- `item_use_sound`:
+
+```json
+{
+  "type": "item_use_sound",
+  "itemId": "item-id",
+  "sound": "sounds/roll.ogg",
+  "x": 12,
+  "y": 8
+}
+```

docs/local.md

@@ -0,0 +1,33 @@
+# Local Development
+
+## Start Server
+
+```bash
+cd /home/jjm/code/chgrid/server
+.venv/bin/python main.py --config config.toml --port 8765
+```
+
+## Start Client
+
+```bash
+cd /home/jjm/code/chgrid/client
+npm run dev -- --host 0.0.0.0 --port 5173
+```
+
+Open: `http://localhost:5173`
+
+## Quick Restarts
+
+Server:
+```bash
+lsof -tiTCP:8765 -sTCP:LISTEN | xargs -r kill
+cd /home/jjm/code/chgrid/server
+nohup .venv/bin/python main.py --config config.toml --port 8765 > /tmp/chgrid-server.log 2>&1 &
+```
+
+Client:
+```bash
+lsof -tiTCP:5173 -sTCP:LISTEN | xargs -r kill
+cd /home/jjm/code/chgrid/client
+nohup npm run dev -- --host 0.0.0.0 --port 5173 > /tmp/chgrid-client.log 2>&1 &
+```