Talon/chat_grid
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

client: require server item schema and drive property UI from metadata

Browse Source
This commit is contained in:
Jage9
2026-02-24 02:49:17 -05:00
parent 477b4d2cf4
commit f7e29ec968
8 changed files with 183 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/item-schema.md
View File

@@ -49,8 +49,8 @@
- Persisted state stores only instance data.
- Global/type-level properties are loaded from server registry in `server/app/item_catalog.py`.
- Per-type use/update validation and message behavior are implemented in per-item modules under `server/app/items/` and wired in `server/app/items/registry.py`.
- Client-side add/edit metadata is handled in `client/src/items/itemRegistry.ts`.
- Per-type use/update validation and message behavior are implemented in per-item modules under `server/app/items/`, discovered via plugins in `server/app/items/types/*/plugin.py`.
- Client-side add/edit metadata is consumed from `welcome.uiDefinitions` via `client/src/items/itemRegistry.ts` (no local fallback definitions).
- End-to-end add-item template: `docs/item-type-template.md`.
## Type Params
@@ -77,7 +77,8 @@
- `mediaChannel`: one of `stereo | mono | left | right`, default `stereo`.
- `mediaEffect`: one of `reverb | echo | flanger | high_pass | low_pass | off`, default `off`.
- `mediaEffectValue`: number, range `0-100`, precision `0.1`.
- `facing`: number, range `0-360`, precision `0.1` (used when `directional=true`).
- `facing`: number, range `0-360`, step `1` (used when `directional=true`).
- UI visibility: `facing` is shown only when `directional=true` (`visibleWhen` metadata).
- `emitRange`: integer, range `5-20`, default `20`.
### `dice`
@@ -148,7 +149,8 @@
- `enabled`: boolean (or `on/off` in updates), default `true`.
- `directional`: boolean (or `on/off` in updates), default `false`.
- `facing`: number, range `0-360`, precision `0.1`.
- `facing`: number, range `0-360`, step `1`.
- UI visibility: `facing` is shown only when `directional=true` (`visibleWhen` metadata).
- `emitRange`: integer, range `1-20`, default `15`.
- `emitVolume`: integer, range `0-100`, default `100`.
- `emitSoundSpeed`: integer, range `0-100`, default `50`; controls emitted sound speed/pitch (`0=0.5x`, `50=1.0x`, `100=2.0x`).

18
docs/item-types.md
View File

@@ -187,9 +187,9 @@ This is behavior-focused documentation for item types and their defaults.
- `emitRange`: integer `5..20`
- Instrument changes reset `voiceMode`/`octave`/`attack`/`decay`/`release`/`brightness` to instrument defaults.
## Adding A New Item Type (Registry V1)
## Adding A New Item Type (Plugin Discovery)
Item types are currently code-registered on both server and client. Server item logic is split per item module and wired through one registry.
Server is the source of truth for item type definitions and metadata. The client consumes server `welcome.uiDefinitions` and only provides UX/runtime behavior.
For a full copy/paste example with plain-English explanation, see `docs/item-type-template.md`.
@@ -197,13 +197,15 @@ For a full copy/paste example with plain-English explanation, see `docs/item-typ
- defaults/capabilities
- property metadata/options
- `validate_update` and `use_item`
2. Server registry: add one entry in `server/app/items/registry.py`:
- `ITEM_MODULES`
- `ITEM_TYPE_ORDER` (if ordering changes)
2. Server plugin: add `server/app/items/types/<item_type>/plugin.py` exporting `ITEM_TYPE_PLUGIN` with:
- `type`
- `order`
- `module`
The server auto-discovers plugins at boot, so no central registry edit is needed.
3. Server models: extend `ItemType` literals in `server/app/models.py` and any packet enums that list item types.
4. Client fallback registry: add type defaults in `client/src/items/itemRegistry.ts` (`DEFAULT_ITEM_TYPE_SEQUENCE`, editable/global fallback metadata).
5. Client protocol/state types: update item-type unions in `client/src/network/protocol.ts` and `client/src/state/gameState.ts`.
6. Tests: add or update server tests under `server/tests/` for use/update validation and cooldown behavior.
4. Client protocol/state types: update item-type unions in `client/src/network/protocol.ts` and `client/src/state/gameState.ts`.
5. Client runtime behavior: add `client/src/items/types/<item_type>/behavior.ts` only if custom client runtime is needed.
6. Tests: add or update server tests under `server/tests/` for use/update validation, unknown-key stripping, and `uiDefinitions` completeness.
### Example Shape

5
docs/protocol-notes.md
View File

@@ -53,10 +53,9 @@ This is a behavior guide for packet semantics beyond raw schemas.
- `itemTypes[].tooltip`: item-level tooltip/help text
- `itemTypes[].editableProperties`: editable property keys by item type
- `itemTypes[].propertyOptions`: menu options for property keys (for example clock `timeZone`)
- `itemTypes[].propertyMetadata`: property-level metadata (`valueType`, optional `range`, optional `tooltip`)
- `itemTypes[].propertyMetadata`: property-level metadata (`valueType`, optional `range`, optional `tooltip`, optional `maxLength`, optional `visibleWhen`)
- `itemTypes[].globalProperties`: non-editable global values (`useSound`, `emitSound`, `useCooldownMs`, `emitRange`, `directional`, `emitSoundSpeed`, `emitSoundTempo`)
- Clients keep local fallback defaults but should prefer server-provided metadata when present.
- Client item UI requires this metadata from the server; there is no fallback item definition map.
## Validation Boundaries