Talon/chat_grid
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
460ad08c02ef2ffb21f3c83b37917a54e9a24c58
chat_grid/docs/protocol-notes.md

2.5 KiB
Raw Blame History

Protocol Notes

This is a behavior guide for packet semantics beyond raw schemas.

Direction

  • Client packet schema lives in server/app/models.py (ClientPacket).
  • Browser-side validation/parsing lives in client/src/network/protocol.ts.
  • Keep these synchronized on every protocol change.

Client -> Server

  • update_position: authoritative player position update.
  • update_nickname: nickname change request (server enforces uniqueness).
  • chat_message: player chat.
  • ping: latency measurement.
  • item_add, item_pickup, item_drop, item_delete, item_use, item_update: item actions.

Server -> Client

  • welcome: initial snapshot with users/items plus server UI/world metadata.
  • signal: forwarded WebRTC offer/answer/ICE.
  • update_position, update_nickname, user_left: presence updates.
  • chat_message: system and user chat stream.
  • pong: ping response.
  • nickname_result: accepted/rejected nickname result.
  • item_upsert: full item replacement after mutation.
  • item_remove: item deletion.
  • item_action_result: action success/failure and user-facing message.
  • item_use_sound: spatial one-shot sound on successful item use (if useSound configured).

Item Packet Behavior

  • item_upsert is full-state replacement for one item, not partial patch.
  • item_action_result messages are intended for direct screen-reader/user status feedback.
  • item_use_sound contains absolute item world coordinates (x, y) and sound path.

Welcome Metadata

  • welcome.worldConfig.gridSize: server-authoritative grid size used by clients for bounds/drawing.

  • welcome.uiDefinitions: server-provided item UI definitions:

    • itemTypeOrder: add-item menu order
    • 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[].globalProperties: non-editable global values (useSound, emitSound, useCooldownMs, emitRange, directional, emitSoundSpeed, emitSoundTempo, emitSoundReverse)

  • Clients keep local fallback defaults but should prefer server-provided metadata when present.

Validation Boundaries

  • Server is authoritative for all action validation and normalization.
  • Client validates incoming packet shapes and applies runtime behavior.
  • Client-side item edit validation is convenience only; server remains source of truth.