Compare commits
8 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 agent-bot
|
1aa41dde90 | ||
|
agent-bot
|
3a0848c80c | ||
|
agent-bot
|
c8d910b1fa | ||
|
agent-bot
|
4a9fa49fa5 | ||
|
agent-bot
|
1a394985b6 | ||
|
agent-bot
|
5f78ce61ec | ||
|
agent-bot
|
ad8e3c0369 | ||
|
agent-bot
|
e05e4cbb4f |
-10
@@ -1,10 +0,0 @@
|
|||||||
# Godot editor cache / generated files
|
|
||||||
.godot/
|
|
||||||
|
|
||||||
# Godot export artifacts
|
|
||||||
export/
|
|
||||||
*.tmp
|
|
||||||
|
|
||||||
# OS
|
|
||||||
.DS_Store
|
|
||||||
Thumbs.db
|
|
||||||
@@ -1,462 +0,0 @@
|
|||||||
# Avatar Component System & glTF Attachment Spec
|
|
||||||
|
|
||||||
> **Status:** Proposed
|
|
||||||
> **Owner:** Platform team
|
|
||||||
> **Related:** Server authority + client prediction, world chunk data format
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
This document specifies the **avatar component system** for **agp-game**, a
|
|
||||||
Godot-based multiplayer game. It defines:
|
|
||||||
|
|
||||||
- How an avatar is decomposed into **body parts** and **attachment slots**.
|
|
||||||
- How **cosmetic attachments** (clothing, accessories, gear) mount onto the
|
|
||||||
base body.
|
|
||||||
- The **glTF/GLB format requirements** that all avatar assets must satisfy so
|
|
||||||
they can be loaded, skinned, and networked consistently.
|
|
||||||
|
|
||||||
The goal is a **modular, data-driven avatar pipeline**: a single base body rig
|
|
||||||
plus swappable attachments, all authored in glTF and consumed by a shared Godot
|
|
||||||
runtime. This enables player customization, cosmetic monetization, and
|
|
||||||
server-authoritative validation of what a player is wearing.
|
|
||||||
|
|
||||||
### 1.1 Design Goals
|
|
||||||
|
|
||||||
- **Modularity:** Body parts and attachments are independent assets that can be
|
|
||||||
combined at runtime without re-exporting.
|
|
||||||
- **Consistency:** A single, well-defined skeleton and slot convention so any
|
|
||||||
attachment fits any base body.
|
|
||||||
- **Networkability:** The avatar's composition is expressed as a compact,
|
|
||||||
serializable **loadout** that the server can validate and replicate.
|
|
||||||
- **Performance:** Attachments are skinned to the same skeleton and share
|
|
||||||
materials where possible to minimize draw calls and skinning cost.
|
|
||||||
- **Tooling-friendly:** Assets are authored in standard glTF 2.0 and validated
|
|
||||||
by a build-time checker.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Avatar Decomposition
|
|
||||||
|
|
||||||
### 2.1 The Base Body
|
|
||||||
|
|
||||||
Every avatar is built on a **base body** — a single glTF asset containing:
|
|
||||||
|
|
||||||
- A **skeleton** (the canonical rig, see §3).
|
|
||||||
- A **base mesh** for the skin/body (head, torso, arms, legs).
|
|
||||||
- **Attachment points** (empty nodes) that define where accessories mount.
|
|
||||||
|
|
||||||
The base body is the only asset that carries the skeleton. Attachments reference
|
|
||||||
the skeleton by **bone name** and are skinned to it; they never carry their own
|
|
||||||
rig.
|
|
||||||
|
|
||||||
### 2.2 Body Parts vs. Attachments
|
|
||||||
|
|
||||||
Two distinct concepts:
|
|
||||||
|
|
||||||
| Concept | Definition | Example |
|
|
||||||
|----------------|-------------------------------------------------------------------------|----------------------------------|
|
|
||||||
| **Body part** | A mesh that replaces part of the base body's skin (e.g., a different head, a tail, wings). | Alternate head, cybernetic arm |
|
|
||||||
| **Attachment** | A mesh that mounts *on top of* the body without replacing it (clothing, accessories). | Shirt, hat, glasses, backpack |
|
|
||||||
|
|
||||||
The distinction matters for **slot exclusivity** and **layering**:
|
|
||||||
|
|
||||||
- **Body parts** are *exclusive* per slot — only one head can be equipped.
|
|
||||||
- **Attachments** are *layered* — a hat and glasses can coexist, and both sit
|
|
||||||
above the head mesh.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Skeleton & Slot Convention
|
|
||||||
|
|
||||||
### 3.1 Canonical Skeleton
|
|
||||||
|
|
||||||
All avatars share a **canonical skeleton** with a fixed set of bone names. This
|
|
||||||
is the contract that lets any attachment fit any body. The skeleton follows a
|
|
||||||
humanoid convention (Godot's `Humanoid` profile / glTF VRM-style naming).
|
|
||||||
|
|
||||||
Required bones (subset of the full rig):
|
|
||||||
|
|
||||||
```
|
|
||||||
Root
|
|
||||||
├── Hips
|
|
||||||
│ ├── Spine
|
|
||||||
│ │ ├── Chest
|
|
||||||
│ │ │ ├── Neck
|
|
||||||
│ │ │ │ └── Head
|
|
||||||
│ │ │ │ ├── HeadTop # hat / hair mount
|
|
||||||
│ │ │ │ ├── Jaw # face accessories
|
|
||||||
│ │ │ │ └── LeftEye / RightEye
|
|
||||||
│ │ │ ├── LeftShoulder
|
|
||||||
│ │ │ │ └── LeftUpperArm
|
|
||||||
│ │ │ │ └── LeftLowerArm
|
|
||||||
│ │ │ │ └── LeftHand
|
|
||||||
│ │ │ └── RightShoulder
|
|
||||||
│ │ │ └── RightUpperArm
|
|
||||||
│ │ │ └── RightLowerArm
|
|
||||||
│ │ │ └── RightHand
|
|
||||||
│ │ └── (Chest children for torso attachments)
|
|
||||||
│ ├── LeftUpperLeg
|
|
||||||
│ │ └── LeftLowerLeg
|
|
||||||
│ │ └── LeftFoot
|
|
||||||
│ └── RightUpperLeg
|
|
||||||
│ └── RightLowerLeg
|
|
||||||
│ └── RightFoot
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rules:**
|
|
||||||
|
|
||||||
- Bone names are **case-sensitive** and must match exactly.
|
|
||||||
- The skeleton is **T-pose** at rest for consistent skinning.
|
|
||||||
- Attachments must be skinned to **at least** the bones they deform; static
|
|
||||||
accessories may be parented to a single bone (e.g., a hat parented to `Head`).
|
|
||||||
|
|
||||||
### 3.2 Attachment Slots
|
|
||||||
|
|
||||||
Slots are the **logical mount points** for body parts and attachments. Each slot
|
|
||||||
maps to one or more bones and defines what can be equipped there.
|
|
||||||
|
|
||||||
| Slot ID | Category | Mount bone(s) | Exclusivity | Example assets |
|
|
||||||
|----------------|--------------|--------------------|-------------|-------------------------------|
|
|
||||||
| `head` | body part | `Head` | exclusive | alternate head, face |
|
|
||||||
| `hair` | attachment | `HeadTop` | exclusive | hairstyles, hats |
|
|
||||||
| `face` | attachment | `Jaw` | exclusive | glasses, masks, beards |
|
|
||||||
| `torso` | body part | `Chest` | exclusive | alternate torso |
|
|
||||||
| `chest` | attachment | `Chest` | exclusive | shirts, armor, chest gear |
|
|
||||||
| `back` | attachment | `Chest` (back) | exclusive | backpacks, wings, capes |
|
|
||||||
| `left_arm` | body part | `LeftUpperArm` | exclusive | alternate arm |
|
|
||||||
| `right_arm` | body part | `RightUpperArm` | exclusive | alternate arm |
|
|
||||||
| `left_hand` | attachment | `LeftHand` | exclusive | gloves, weapons (held) |
|
|
||||||
| `right_hand` | attachment | `RightHand` | exclusive | gloves, weapons (held) |
|
|
||||||
| `legs` | body part | `Hips` | exclusive | alternate legs |
|
|
||||||
| `pants` | attachment | `Hips` | exclusive | pants, skirts |
|
|
||||||
| `left_foot` | attachment | `LeftFoot` | exclusive | shoes |
|
|
||||||
| `right_foot` | attachment | `RightFoot` | exclusive | shoes |
|
|
||||||
| `accessory` | attachment | `Root` (free) | multiple | belts, jewelry, floating items|
|
|
||||||
|
|
||||||
**Slot semantics:**
|
|
||||||
|
|
||||||
- **`exclusive`** slots allow at most one equipped item at a time.
|
|
||||||
- The **`accessory`** slot is *multi-slot* — multiple accessories may be equipped
|
|
||||||
simultaneously (bounded by a configurable limit, e.g., 8).
|
|
||||||
- **Body-part slots** (`head`, `torso`, `legs`, `left_arm`, `right_arm`) replace
|
|
||||||
the corresponding base mesh. When a body part is equipped, the base mesh for
|
|
||||||
that region is hidden.
|
|
||||||
- **Attachment slots** layer on top of the base mesh and never hide it.
|
|
||||||
|
|
||||||
### 3.3 Slot → Bone Mapping
|
|
||||||
|
|
||||||
Each slot declares a **primary mount bone** and an optional **secondary bone
|
|
||||||
list** for skinning. The runtime uses this to:
|
|
||||||
|
|
||||||
1. Parent static accessories to the mount bone.
|
|
||||||
2. Skin skinned attachments to the union of the slot's bones.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. glTF/GLB Format Requirements
|
|
||||||
|
|
||||||
All avatar assets (base bodies, body parts, attachments) are distributed as
|
|
||||||
**glTF 2.0** (`.gltf` + external buffers/textures) or **GLB** (`.glb`, binary
|
|
||||||
container). GLB is the preferred distribution format for runtime loading.
|
|
||||||
|
|
||||||
### 4.1 Required Conventions
|
|
||||||
|
|
||||||
| Concern | Requirement |
|
|
||||||
|--------------------|------------------------------------------------------------------------------|
|
|
||||||
| **Format** | glTF 2.0 (`.gltf` or `.glb`). GLB preferred for runtime. |
|
|
||||||
| **Coordinate system** | glTF standard: **+Y up, +Z forward, right-handed**. Godot converts to its own convention on import. |
|
|
||||||
| **Units** | Meters. Avatar height ~1.8 m at the `Root` bone. |
|
|
||||||
| **Skeleton** | Single skeleton per asset; bone names per §3.1. |
|
|
||||||
| **Skinning** | `skins` + `nodes` with `JOINTS_0` / `WEIGHTS_0` accessors. |
|
|
||||||
| **Pose** | T-pose at rest. |
|
|
||||||
| **Materials** | PBR metallic-roughness. Use `KHR_materials_unlit` for emissive/UI-only items. |
|
|
||||||
| **Textures** | Max 2048×2048; power-of-two preferred. Use `KHR_texture_basisu` (BasisU) for runtime. |
|
|
||||||
| **Animation** | Optional. If present, must not rename or remove canonical bones. |
|
|
||||||
|
|
||||||
### 4.2 Asset Metadata (extras)
|
|
||||||
|
|
||||||
Each asset **must** declare its slot and identity in the glTF `asset.extras`
|
|
||||||
object. This is the machine-readable contract consumed by the build pipeline and
|
|
||||||
runtime.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"asset": {
|
|
||||||
"version": "2.0",
|
|
||||||
"extras": {
|
|
||||||
"agp": {
|
|
||||||
"type": "attachment", // "base_body" | "body_part" | "attachment"
|
|
||||||
"slot": "chest", // slot ID from §3.2
|
|
||||||
"id": "shirt_bandit_01", // globally unique asset id
|
|
||||||
"display_name": "Bandit Shirt",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"mount_bone": "Chest", // primary mount bone
|
|
||||||
"skin_bones": ["Chest", "Spine", "LeftUpperArm", "RightUpperArm"],
|
|
||||||
"exclusive": true, // matches slot exclusivity
|
|
||||||
"tags": ["cloth", "common"],
|
|
||||||
"author": "platform-team"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Validation rules for `extras.agp`:**
|
|
||||||
|
|
||||||
- `type` must be one of `base_body`, `body_part`, `attachment`.
|
|
||||||
- `slot` must be a known slot ID (§3.2).
|
|
||||||
- `mount_bone` must exist in the canonical skeleton.
|
|
||||||
- `skin_bones` must all exist in the canonical skeleton.
|
|
||||||
- `exclusive` must match the slot's declared exclusivity.
|
|
||||||
- `id` must be unique across the asset catalog.
|
|
||||||
|
|
||||||
### 4.3 Node Naming Convention
|
|
||||||
|
|
||||||
To make assets self-describing and mergeable, nodes follow a convention:
|
|
||||||
|
|
||||||
- **Base body:** the mesh node is named `Body`; the skeleton root is `Root`.
|
|
||||||
- **Body part:** the mesh node is named `<SlotID>_Mesh` (e.g., `head_Mesh`).
|
|
||||||
- **Attachment:** the mesh node is named `<SlotID>_<AssetID>` (e.g.,
|
|
||||||
`chest_shirt_bandit_01`).
|
|
||||||
- **Attachment points** (empty nodes) on the base body are named
|
|
||||||
`attach_<slot>` (e.g., `attach_head`, `attach_left_hand`).
|
|
||||||
|
|
||||||
### 4.4 Material & Texture Requirements
|
|
||||||
|
|
||||||
- All materials use the **metallic-roughness** PBR model.
|
|
||||||
- Textures are embedded in the GLB or referenced as external files; external
|
|
||||||
references must be relative paths within the asset package.
|
|
||||||
- **Color customization** is supported via a `baseColorFactor` tint applied at
|
|
||||||
runtime (multiplied over the albedo). Assets should use a neutral albedo
|
|
||||||
(white/gray) where tinting is intended.
|
|
||||||
- **Masked/transparent** materials must set the correct alpha mode
|
|
||||||
(`MASK` or `BLEND`) and `alphaCutoff`.
|
|
||||||
|
|
||||||
### 4.5 Skeleton Merging at Runtime
|
|
||||||
|
|
||||||
When an attachment is loaded, the runtime **merges** it onto the base body:
|
|
||||||
|
|
||||||
1. Load the base body (skeleton + base meshes).
|
|
||||||
2. Load each equipped attachment.
|
|
||||||
3. For each attachment, **re-target its skin** to the base body's skeleton by
|
|
||||||
bone name (no re-export needed).
|
|
||||||
4. Parent static accessories to their `mount_bone`.
|
|
||||||
5. Hide base meshes for any equipped body-part slots.
|
|
||||||
6. Apply material tints and merge into the render tree.
|
|
||||||
|
|
||||||
The merge is **name-based** — bone names must match exactly (§3.1). This is the
|
|
||||||
core reason for the strict naming contract.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Loadout Model (Network & Persistence)
|
|
||||||
|
|
||||||
The avatar's composition is serialized as a **loadout** — a compact, ordered
|
|
||||||
list of equipped asset IDs. This is what the server validates, persists, and
|
|
||||||
replicates.
|
|
||||||
|
|
||||||
### 5.1 Loadout JSON
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"base_body": "base_human_male_01",
|
|
||||||
"slots": {
|
|
||||||
"head": "head_cyber_01",
|
|
||||||
"hair": "hair_mohawk_01",
|
|
||||||
"face": null,
|
|
||||||
"torso": null,
|
|
||||||
"chest": "chest_bandit_01",
|
|
||||||
"back": "backpack_01",
|
|
||||||
"left_arm": null,
|
|
||||||
"right_arm": null,
|
|
||||||
"left_hand": "glove_leather_01",
|
|
||||||
"right_hand": "glove_leather_01",
|
|
||||||
"legs": null,
|
|
||||||
"pants": "pants_cargo_01",
|
|
||||||
"left_foot": "shoe_boot_01",
|
|
||||||
"right_foot": "shoe_boot_01",
|
|
||||||
"accessory": ["belt_01", "necklace_01"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rules:**
|
|
||||||
|
|
||||||
- `base_body` is required and must reference a valid `base_body` asset.
|
|
||||||
- Each exclusive slot holds **at most one** asset id (or `null`).
|
|
||||||
- `accessory` is an array (0..N, bounded).
|
|
||||||
- The server validates that every id exists in the catalog and that slot
|
|
||||||
exclusivity is respected.
|
|
||||||
|
|
||||||
### 5.2 Network Replication
|
|
||||||
|
|
||||||
The loadout is replicated as part of the player's spawn/state data:
|
|
||||||
|
|
||||||
```
|
|
||||||
spawn_entity:
|
|
||||||
entity_id: uint32
|
|
||||||
type: player
|
|
||||||
transform: { x, y, rot }
|
|
||||||
props:
|
|
||||||
loadout_hash: uint32 # hash of the loadout for change detection
|
|
||||||
loadout: { ... } # full loadout on spawn / on change
|
|
||||||
```
|
|
||||||
|
|
||||||
- The **full loadout** is sent on spawn and whenever it changes (reliable).
|
|
||||||
- A **`loadout_hash`** lets clients skip re-resolving assets if unchanged.
|
|
||||||
- The server is the **authority** on the loadout; clients send *requests* to
|
|
||||||
change equipment, and the server validates and broadcasts the result.
|
|
||||||
|
|
||||||
### 5.3 Server-Side Validation
|
|
||||||
|
|
||||||
The server rejects a loadout if:
|
|
||||||
|
|
||||||
- `base_body` is missing or unknown.
|
|
||||||
- Any slot references an unknown asset id.
|
|
||||||
- An exclusive slot has more than one item.
|
|
||||||
- An asset's declared `slot` does not match the slot it is placed in.
|
|
||||||
- The accessory list exceeds the configured limit.
|
|
||||||
- The asset is not owned/unlocked by the player (for gated cosmetics).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Godot Runtime Architecture
|
|
||||||
|
|
||||||
### 6.1 Node Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
Avatar (Node3D)
|
|
||||||
├── Skeleton3D # canonical skeleton (from base body)
|
|
||||||
├── BodyMeshes # base body meshes (skinned to Skeleton3D)
|
|
||||||
│ ├── head_Mesh
|
|
||||||
│ ├── torso_Mesh
|
|
||||||
│ └── ...
|
|
||||||
├── Attachments # equipped attachments
|
|
||||||
│ ├── chest_shirt_bandit_01
|
|
||||||
│ ├── hair_mohawk_01
|
|
||||||
│ └── ...
|
|
||||||
└── AttachmentPoints # empty nodes for dynamic mounting
|
|
||||||
├── attach_head
|
|
||||||
├── attach_left_hand
|
|
||||||
└── ...
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 Core Classes
|
|
||||||
|
|
||||||
| Class | Responsibility |
|
|
||||||
|--------------------------|-------------------------------------------------------------|
|
|
||||||
| `AvatarSystem` | Loads base body + attachments, resolves loadouts, owns the avatar node. |
|
|
||||||
| `AvatarLoader` | glTF/GLB import, skeleton merge, skin re-targeting. |
|
|
||||||
| `AvatarSlotRegistry` | Static registry of slot definitions (id, bones, exclusivity).|
|
|
||||||
| `AvatarLoadout` | Serializable loadout model + validation. |
|
|
||||||
| `AvatarCatalog` | Asset catalog (id → asset metadata + resource path). |
|
|
||||||
| `AvatarVisualizer` | Builds the render tree from a loadout. |
|
|
||||||
|
|
||||||
### 6.3 Loading Pipeline
|
|
||||||
|
|
||||||
```
|
|
||||||
loadout JSON
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
AvatarCatalog.resolve(loadout) # id → asset metadata + GLB path
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
AvatarLoader.load_base_body() # import GLB, extract skeleton + base meshes
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
for each equipped slot:
|
|
||||||
AvatarLoader.load_attachment()# import GLB, re-target skin to skeleton
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
AvatarVisualizer.assemble() # parent, hide replaced parts, apply tints
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Avatar node ready for render
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.4 Performance Considerations
|
|
||||||
|
|
||||||
- **Shared skeleton:** All meshes skin to one `Skeleton3D`, so skinning is
|
|
||||||
computed once per frame.
|
|
||||||
- **Material batching:** Attachments that share a material are merged into a
|
|
||||||
single mesh where possible (static accessories).
|
|
||||||
- **LOD:** Optional LOD variants per asset; the runtime selects based on
|
|
||||||
distance.
|
|
||||||
- **Caching:** Resolved loadouts and imported GLB resources are cached by
|
|
||||||
`AvatarCatalog` to avoid re-importing on respawn or re-join.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Asset Pipeline & Validation
|
|
||||||
|
|
||||||
### 7.1 Build-Time Validation
|
|
||||||
|
|
||||||
A build-time checker validates every asset before it enters the catalog:
|
|
||||||
|
|
||||||
1. **Format check:** valid glTF 2.0 / GLB.
|
|
||||||
2. **Metadata check:** `extras.agp` present and valid (§4.2).
|
|
||||||
3. **Skeleton check:** all `skin_bones` exist in the canonical skeleton.
|
|
||||||
4. **Slot check:** `slot` is known and `exclusive` matches.
|
|
||||||
5. **Mesh check:** meshes are skinned (or static accessories parented to a bone).
|
|
||||||
6. **Texture check:** sizes, formats, and alpha modes are valid.
|
|
||||||
7. **Uniqueness check:** `id` is unique.
|
|
||||||
|
|
||||||
### 7.2 Catalog Manifest
|
|
||||||
|
|
||||||
The catalog is a JSON manifest mapping asset ids to metadata and resource paths:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"assets": {
|
|
||||||
"base_human_male_01": {
|
|
||||||
"type": "base_body",
|
|
||||||
"path": "res://assets/avatars/base_human_male_01.glb",
|
|
||||||
"version": "1.0.0"
|
|
||||||
},
|
|
||||||
"chest_bandit_01": {
|
|
||||||
"type": "attachment",
|
|
||||||
"slot": "chest",
|
|
||||||
"path": "res://assets/avatars/chest_bandit_01.glb",
|
|
||||||
"version": "1.0.0"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Security & Anti-Cheat
|
|
||||||
|
|
||||||
- **Server-authoritative loadouts:** Clients only *request* equipment changes;
|
|
||||||
the server validates against the catalog and the player's owned items.
|
|
||||||
- **No client asset injection:** Clients cannot send arbitrary GLB data; they
|
|
||||||
reference catalog ids only.
|
|
||||||
- **Rate limiting:** Equipment-change requests are rate-limited per peer.
|
|
||||||
- **Hash verification:** The `loadout_hash` lets the server detect tampered or
|
|
||||||
stale loadout state.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Open Questions / Future Work
|
|
||||||
|
|
||||||
- **Morph targets / blendshapes:** Support for facial expressions and body
|
|
||||||
morphs (e.g., height, muscle) via glTF morph targets.
|
|
||||||
- **Physics attachments:** Cloth simulation for capes/skirts (Godot cloth).
|
|
||||||
- **Dynamic tinting UI:** A color-picker that writes `baseColorFactor` tints.
|
|
||||||
- **VRM compatibility:** Consider supporting VRM (a glTF extension for
|
|
||||||
humanoid avatars) as an import source.
|
|
||||||
- **Attachment LOD streaming:** Streaming high-res attachments on demand.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Summary
|
|
||||||
|
|
||||||
| Concern | Decision |
|
|
||||||
|------------------------|-------------------------------------------------------|
|
|
||||||
| Format | glTF 2.0 / GLB (GLB preferred for runtime) |
|
|
||||||
| Skeleton | Single canonical humanoid skeleton, name-based merge |
|
|
||||||
| Slots | Fixed slot registry; exclusive body parts + layered attachments |
|
|
||||||
| Loadout | Compact JSON; server-authoritative and validated |
|
|
||||||
| Replication | Full loadout on spawn/change + `loadout_hash` |
|
|
||||||
| Runtime | Godot `Skeleton3D` + name-based skin re-targeting |
|
|
||||||
| Validation | Build-time asset checker + runtime catalog validation |
|
|
||||||
@@ -1,426 +0,0 @@
|
|||||||
# Content Moderation & Age Verification Architecture
|
|
||||||
|
|
||||||
> **Status:** Proposed
|
|
||||||
> **Owner:** Platform team
|
|
||||||
> **Related:** Server authority + client prediction, avatar component system, backend auth (JWT)
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
This document specifies the **content moderation** and **age verification**
|
|
||||||
architecture for **agp-game**, a Godot-based multiplayer game built by
|
|
||||||
autonomous agents. It defines:
|
|
||||||
|
|
||||||
- How **content flags** propagate through the system across the three primary
|
|
||||||
content types: **assets**, **rooms**, and **scripts**.
|
|
||||||
- How flags are **evaluated, aggregated, and enforced** at load time, at
|
|
||||||
runtime, and at the network boundary.
|
|
||||||
- The **age verification flow**, combining a lightweight **self-declaration**
|
|
||||||
with an optional **ID check hook** for higher-assurance verification.
|
|
||||||
|
|
||||||
The goal is a **single, consistent moderation pipeline** that applies the same
|
|
||||||
rules to user-generated content (UGC) regardless of whether it is a 3D asset, a
|
|
||||||
room definition, or a script, and that gates access to mature content behind a
|
|
||||||
verifiable age gate.
|
|
||||||
|
|
||||||
### 1.1 Design Goals
|
|
||||||
|
|
||||||
- **Uniformity:** One flag vocabulary and one propagation mechanism across
|
|
||||||
assets, rooms, and scripts.
|
|
||||||
- **Composability:** Flags on a room aggregate the flags of the assets and
|
|
||||||
scripts it contains; flags on a world aggregate the flags of its rooms.
|
|
||||||
- **Enforcement at the boundary:** The server is authoritative for what content
|
|
||||||
a client may load or receive, mirroring the server-authoritative networking
|
|
||||||
model.
|
|
||||||
- **Privacy-preserving age checks:** Self-declaration requires no PII; the ID
|
|
||||||
check hook is optional, pluggable, and never stores raw identity documents.
|
|
||||||
- **Auditability:** Every flag decision is logged with a reason, an actor, and
|
|
||||||
a timestamp so moderation actions are reviewable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Content Flag Vocabulary
|
|
||||||
|
|
||||||
All content carries a set of **content flags**. A flag is a typed, immutable
|
|
||||||
label with a **severity** and a **scope**. Flags are the atomic unit of
|
|
||||||
moderation; everything else (aggregation, enforcement, gating) operates on
|
|
||||||
flags.
|
|
||||||
|
|
||||||
### 2.1 Flag Definition
|
|
||||||
|
|
||||||
A flag is a structured record:
|
|
||||||
|
|
||||||
| Field | Type | Description |
|
|
||||||
|------------|-----------|--------------------------------------------------------------------------|
|
|
||||||
| `id` | `string` | Stable machine-readable identifier, e.g. `violence.gore`. |
|
|
||||||
| `label` | `string` | Human-readable name, e.g. "Graphic Gore". |
|
|
||||||
| `category` | `enum` | One of `violence`, `sexual`, `language`, `substance`, `gambling`, `horror`, `hate`, `custom`. |
|
|
||||||
| `severity` | `enum` | One of `none`, `mild`, `moderate`, `severe`. |
|
|
||||||
| `scope` | `enum` | One of `visual`, `audio`, `text`, `behavior`, `interaction`. |
|
|
||||||
| `mature` | `bool` | Whether this flag triggers the age gate (see §5). |
|
|
||||||
| `reason` | `string` | Free-text justification supplied by the flagger. |
|
|
||||||
| `source` | `enum` | One of `author`, `moderator`, `automated`, `community`. |
|
|
||||||
|
|
||||||
### 2.2 Canonical Flag Set
|
|
||||||
|
|
||||||
The platform defines a **canonical registry** of flags so that different
|
|
||||||
content types and different flaggers use the same vocabulary. Examples:
|
|
||||||
|
|
||||||
| id | category | severity | scope | mature |
|
|
||||||
|-----------------------------|------------|-----------|--------------|--------|
|
|
||||||
| `violence.none` | violence | none | visual | false |
|
|
||||||
| `violence.mild` | violence | mild | visual | false |
|
|
||||||
| `violence.gore` | violence | severe | visual | true |
|
|
||||||
| `sexual.suggestive` | sexual | mild | visual | true |
|
|
||||||
| `sexual.explicit` | sexual | severe | visual | true |
|
|
||||||
| `language.mild` | language | mild | text | false |
|
|
||||||
| `language.profanity` | language | moderate | text | false |
|
|
||||||
| `substance.references` | substance | mild | text | false |
|
|
||||||
| `gambling.simulated` | gambling | moderate | behavior | true |
|
|
||||||
| `horror.jumpscare` | horror | mild | audio/visual | false |
|
|
||||||
| `hate.hateful` | hate | severe | text | true |
|
|
||||||
|
|
||||||
The registry is **data-driven** (a JSON/YAML manifest shipped with the server)
|
|
||||||
so new flags can be added without code changes.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Flag Propagation Model
|
|
||||||
|
|
||||||
Flags propagate through the system along the **content dependency graph**. The
|
|
||||||
three content types form a hierarchy:
|
|
||||||
|
|
||||||
```
|
|
||||||
World
|
|
||||||
└── Room
|
|
||||||
├── Asset (mesh, texture, audio, animation, material)
|
|
||||||
└── Script (behavior, dialogue, event logic)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.1 Propagation Rules
|
|
||||||
|
|
||||||
1. **Explicit flags** are set directly on a content item by its author or a
|
|
||||||
moderator.
|
|
||||||
2. **Inherited flags** flow upward: a room's effective flag set is the **union**
|
|
||||||
of its own explicit flags and the flags of every asset and script it
|
|
||||||
references.
|
|
||||||
3. **Aggregation** uses the **maximum severity** per category across all
|
|
||||||
contributing items. A room containing one `violence.gore` asset and one
|
|
||||||
`violence.none` asset is `violence.severe`.
|
|
||||||
4. **Maturity is monotonic:** if any contributing item is `mature`, the
|
|
||||||
containing room and world are `mature`.
|
|
||||||
5. **Cycles are impossible** by construction: content references form a DAG
|
|
||||||
(an asset cannot contain a room; a room cannot contain itself).
|
|
||||||
|
|
||||||
### 3.2 Propagation Through the Pipeline
|
|
||||||
|
|
||||||
Flags are attached at **authoring time** and carried through every stage:
|
|
||||||
|
|
||||||
```
|
|
||||||
Authoring ──► Upload ──► Validation ──► Storage ──► Distribution ──► Runtime
|
|
||||||
│ │ │ │ │ │
|
|
||||||
│ flag │ flag │ automated │ flag │ flag │ flag
|
|
||||||
│ declared │ preserved │ scan adds │ indexed │ re-checked │ enforced
|
|
||||||
│ │ │ flags │ │ │
|
|
||||||
```
|
|
||||||
|
|
||||||
| Stage | Responsibility |
|
|
||||||
|--------------|-------------------------------------------------------------------------|
|
|
||||||
| **Authoring**| Author declares flags in the editor/upload UI. |
|
|
||||||
| **Upload** | Flags are validated against the canonical registry; unknown flags rejected. |
|
|
||||||
| **Validation**| Automated scanner (hash-based + heuristic) adds flags for detected content. |
|
|
||||||
| **Storage** | Flags are stored alongside the content record and indexed for queries. |
|
|
||||||
| **Distribution**| Flags are re-checked against the current registry before serving. |
|
|
||||||
| **Runtime** | The client enforces flags before loading content (see §4). |
|
|
||||||
|
|
||||||
### 3.3 Data Model
|
|
||||||
|
|
||||||
Flags are stored as a **normalized join table** so they can be queried and
|
|
||||||
aggregated efficiently:
|
|
||||||
|
|
||||||
```
|
|
||||||
content_item (id, type, owner_id, ...)
|
|
||||||
content_flag (content_id, flag_id, source, reason, created_at, actor_id)
|
|
||||||
flag_registry (id, category, severity, scope, mature, ...)
|
|
||||||
```
|
|
||||||
|
|
||||||
Aggregation is computed by a SQL view / query that joins a content item's
|
|
||||||
transitive dependencies. Because the graph is a DAG, this is a bounded
|
|
||||||
recursive query (PostgreSQL `WITH RECURSIVE`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Enforcement
|
|
||||||
|
|
||||||
Enforcement happens at three layers, in order:
|
|
||||||
|
|
||||||
### 4.1 Load-Time Enforcement (Server)
|
|
||||||
|
|
||||||
Before a client is allowed to **request** content, the server evaluates the
|
|
||||||
content's effective flag set against the requesting account's **content
|
|
||||||
preferences** and **age verification status**:
|
|
||||||
|
|
||||||
- If the content is `mature` and the account is **not age-verified**, the
|
|
||||||
request is **rejected** with a `403 MATURE_CONTENT_REQUIRES_VERIFICATION`.
|
|
||||||
- If the content's flags exceed the account's **content filter** (a per-account
|
|
||||||
severity threshold per category), the request is rejected or the offending
|
|
||||||
content is **stripped** (e.g., audio muted, mesh hidden, script not loaded).
|
|
||||||
|
|
||||||
### 4.2 Runtime Enforcement (Client)
|
|
||||||
|
|
||||||
The client receives a **manifest** of allowed content from the server. It never
|
|
||||||
loads content that is not in the manifest. This prevents a malicious or buggy
|
|
||||||
client from bypassing the server's filter by loading content directly.
|
|
||||||
|
|
||||||
- Assets not in the manifest are **not instantiated**.
|
|
||||||
- Scripts not in the manifest are **not executed**.
|
|
||||||
- Rooms not in the manifest are **not entered**.
|
|
||||||
|
|
||||||
### 4.3 Network Boundary Enforcement
|
|
||||||
|
|
||||||
The server **filters replication** based on flags:
|
|
||||||
|
|
||||||
- Mature or filtered content is **not replicated** to clients that cannot
|
|
||||||
receive it.
|
|
||||||
- A room's flag set is broadcast in the room metadata so clients can show a
|
|
||||||
warning before entry.
|
|
||||||
|
|
||||||
### 4.4 Enforcement Decision Flow
|
|
||||||
|
|
||||||
```
|
|
||||||
Client requests content C for account A
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Compute effective flags F(C) [union + max-severity aggregation]
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Is A age-verified? ──no──► Is F(C).mature? ──yes──► REJECT (403)
|
|
||||||
│ yes │ no
|
|
||||||
▼ ▼
|
|
||||||
Does F(C) exceed A's filter? ──► yes ──► REJECT or STRIP
|
|
||||||
│ no
|
|
||||||
▼
|
|
||||||
Serve content + manifest
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Age Verification Flow
|
|
||||||
|
|
||||||
Age verification is a **two-tier** system:
|
|
||||||
|
|
||||||
- **Tier 1 — Self-declaration:** The user asserts their date of birth. This is
|
|
||||||
fast, requires no PII beyond a birthdate, and is sufficient for most content.
|
|
||||||
- **Tier 2 — ID check (optional hook):** A pluggable identity-verification
|
|
||||||
provider confirms the user is an adult. This raises the account's assurance
|
|
||||||
level and unlocks the highest maturity tier.
|
|
||||||
|
|
||||||
### 5.1 Verification States
|
|
||||||
|
|
||||||
An account has an **age verification status**:
|
|
||||||
|
|
||||||
| Status | Meaning |
|
|
||||||
|-------------------|----------------------------------------------------------------------|
|
|
||||||
| `unverified` | No declaration on file. |
|
|
||||||
| `self_declared` | User declared a birthdate; **not** independently confirmed. |
|
|
||||||
| `id_verified` | User passed the ID check hook; independently confirmed adult. |
|
|
||||||
| `rejected` | ID check failed or declaration was inconsistent. |
|
|
||||||
|
|
||||||
### 5.2 Tier 1 — Self-Declaration Flow
|
|
||||||
|
|
||||||
```
|
|
||||||
User submits { date_of_birth }
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Server validates format & plausibility (age 13–120, not in future)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Compute age from DOB
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
age >= 18 ──► status = self_declared (adult)
|
|
||||||
age >= 13 ──► status = self_declared (minor, restricted)
|
|
||||||
age < 13 ──► status = rejected (below minimum platform age)
|
|
||||||
```
|
|
||||||
|
|
||||||
- The DOB is stored **encrypted at rest** and is **never exposed** to other
|
|
||||||
players.
|
|
||||||
- A user may **upgrade** from `self_declared` to `id_verified` at any time via
|
|
||||||
Tier 2.
|
|
||||||
|
|
||||||
### 5.3 Tier 2 — ID Check Hook
|
|
||||||
|
|
||||||
The ID check is an **optional, pluggable hook**. The platform defines an
|
|
||||||
interface; concrete providers (e.g., a third-party KYC service) implement it.
|
|
||||||
|
|
||||||
```
|
|
||||||
User requests ID verification
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Server creates a verification session (idempotent, expiring)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Server calls provider hook: verify(identity_token) -> { adult: bool, ref: string }
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
adult == true ──► status = id_verified, store provider ref (not raw doc)
|
|
||||||
adult == false ─► status = rejected
|
|
||||||
provider error ──► status unchanged, retry allowed
|
|
||||||
```
|
|
||||||
|
|
||||||
**Privacy guarantees:**
|
|
||||||
|
|
||||||
- The platform **never stores** the raw identity document or image.
|
|
||||||
- Only the provider's **opaque reference** and the boolean `adult` result are
|
|
||||||
persisted.
|
|
||||||
- The hook is **asynchronous and idempotent**; a session can be retried without
|
|
||||||
double-charging or double-verifying.
|
|
||||||
|
|
||||||
### 5.4 Hook Interface
|
|
||||||
|
|
||||||
The ID check hook is defined as a backend interface (FastAPI dependency /
|
|
||||||
abstract service):
|
|
||||||
|
|
||||||
```python
|
|
||||||
class IdentityVerificationProvider(Protocol):
|
|
||||||
def create_session(self, user_id: str) -> VerificationSession: ...
|
|
||||||
def verify(self, session_id: str, identity_token: str) -> VerificationResult: ...
|
|
||||||
|
|
||||||
class VerificationResult:
|
|
||||||
adult: bool
|
|
||||||
provider_ref: str | None
|
|
||||||
error: str | None
|
|
||||||
```
|
|
||||||
|
|
||||||
A default **no-op provider** returns `adult=False` with a clear error, so the
|
|
||||||
system runs without any third-party integration until one is configured.
|
|
||||||
|
|
||||||
### 5.5 Age Gate Enforcement
|
|
||||||
|
|
||||||
The age gate is enforced at **load time** (see §4.1):
|
|
||||||
|
|
||||||
| Verification status | Can access `mature` content? |
|
|
||||||
|---------------------|------------------------------|
|
|
||||||
| `unverified` | No |
|
|
||||||
| `self_declared` | Yes (adult) / No (minor) |
|
|
||||||
| `id_verified` | Yes |
|
|
||||||
| `rejected` | No |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Moderation Workflow
|
|
||||||
|
|
||||||
### 6.1 Flagging Sources
|
|
||||||
|
|
||||||
Content can be flagged by:
|
|
||||||
|
|
||||||
- **Author** (self-declared at upload).
|
|
||||||
- **Automated scanner** (hash-based detection, heuristic analysis).
|
|
||||||
- **Community** (players report content; reports become flags after review).
|
|
||||||
- **Moderator** (manual review and override).
|
|
||||||
|
|
||||||
### 6.2 Review Queue
|
|
||||||
|
|
||||||
Community and automated flags enter a **review queue**. A moderator either:
|
|
||||||
|
|
||||||
- **Approves** the flag (it becomes authoritative), or
|
|
||||||
- **Rejects** the flag (it is discarded), or
|
|
||||||
- **Escalates** to a senior moderator for severe/hate flags.
|
|
||||||
|
|
||||||
### 6.3 Actions
|
|
||||||
|
|
||||||
Once a flag is authoritative, a moderator can take actions:
|
|
||||||
|
|
||||||
| Action | Effect |
|
|
||||||
|-----------------|---------------------------------------------------------------|
|
|
||||||
| `warn` | Notify the author; content remains. |
|
|
||||||
| `restrict` | Content hidden from users below a filter threshold. |
|
|
||||||
| `age_gate` | Content marked `mature`; requires age verification. |
|
|
||||||
| `remove` | Content taken down; not served. |
|
|
||||||
| `ban_author` | Author's upload privileges suspended. |
|
|
||||||
|
|
||||||
### 6.4 Audit Log
|
|
||||||
|
|
||||||
Every flag and action is written to an **audit log**:
|
|
||||||
|
|
||||||
```
|
|
||||||
audit_event (id, content_id, actor_id, action, flag_id, reason, created_at)
|
|
||||||
```
|
|
||||||
|
|
||||||
This log is append-only and used for transparency and dispute resolution.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Client-Side Integration (Godot)
|
|
||||||
|
|
||||||
### 7.1 Content Manifest
|
|
||||||
|
|
||||||
The server sends each client a **content manifest** — the set of content the
|
|
||||||
client is permitted to load, derived from the account's verification status and
|
|
||||||
filter. The Godot client:
|
|
||||||
|
|
||||||
- Loads only manifest-listed assets.
|
|
||||||
- Executes only manifest-listed scripts.
|
|
||||||
- Shows a **maturity warning** dialog before entering a room whose effective
|
|
||||||
flags include `mature` content.
|
|
||||||
|
|
||||||
### 7.2 Flag Metadata on Content
|
|
||||||
|
|
||||||
Each content resource carries a `content_flags` metadata field (a Godot
|
|
||||||
`Dictionary` or custom `Resource`). The client uses this for local UI decisions
|
|
||||||
(e.g., showing a warning icon) but **never** as the authority for whether to
|
|
||||||
load — the server manifest is authoritative.
|
|
||||||
|
|
||||||
### 7.3 Age Verification UI
|
|
||||||
|
|
||||||
The client exposes an **age verification screen**:
|
|
||||||
|
|
||||||
- Tier 1: a date-of-birth picker.
|
|
||||||
- Tier 2: a button that opens the ID check provider flow (deep link / webview).
|
|
||||||
|
|
||||||
The client calls the backend endpoints (§8) and reflects the resulting status.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Backend API Surface
|
|
||||||
|
|
||||||
| Method | Path | Description |
|
|
||||||
|--------|-----------------------------------|------------------------------------------------|
|
|
||||||
| `POST` | `/v1/age/declare` | Submit self-declared DOB (Tier 1). |
|
|
||||||
| `POST` | `/v1/age/verify/session` | Create an ID-check session (Tier 2). |
|
|
||||||
| `POST` | `/v1/age/verify/confirm` | Confirm an ID-check session with a token. |
|
|
||||||
| `GET` | `/v1/age/status` | Return the account's verification status. |
|
|
||||||
| `GET` | `/v1/content/{id}/flags` | Return a content item's effective flags. |
|
|
||||||
| `POST` | `/v1/content/{id}/flags` | Add a flag (author/community). |
|
|
||||||
| `POST` | `/v1/moderation/review/{flag_id}` | Moderator approve/reject/escalate. |
|
|
||||||
| `POST` | `/v1/moderation/action` | Apply a moderation action. |
|
|
||||||
| `GET` | `/v1/manifest` | Return the client's permitted content manifest.|
|
|
||||||
|
|
||||||
All endpoints require a valid **JWT** (matching the existing auth stack). The
|
|
||||||
age endpoints additionally require the account to be in a non-`rejected` state.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Security & Privacy Considerations
|
|
||||||
|
|
||||||
- **DOB encryption:** Self-declared birthdates are encrypted at rest; only the
|
|
||||||
derived age and verification status are used in authorization decisions.
|
|
||||||
- **No raw identity storage:** The ID check hook persists only a provider
|
|
||||||
reference and a boolean result.
|
|
||||||
- **Server authority:** The client manifest prevents bypass; the client never
|
|
||||||
trusts its own flag metadata for access decisions.
|
|
||||||
- **Rate limiting:** Age-declaration and ID-check endpoints are rate-limited to
|
|
||||||
prevent abuse and enumeration.
|
|
||||||
- **Auditability:** All flag and verification events are logged append-only.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Open Questions / Future Work
|
|
||||||
|
|
||||||
- **Regional age thresholds:** Different jurisdictions may require different
|
|
||||||
minimum ages; the threshold should be configurable per region.
|
|
||||||
- **Parental controls:** A future feature may let a parent set a content filter
|
|
||||||
on a minor's account.
|
|
||||||
- **Automated scanner accuracy:** The heuristic scanner may produce false
|
|
||||||
positives; a confidence score should be attached to automated flags.
|
|
||||||
- **Offline / local content:** How flags apply to locally-authored content that
|
|
||||||
is never uploaded remains to be defined.
|
|
||||||
@@ -1,286 +0,0 @@
|
|||||||
# Multiplayer Networking Architecture
|
|
||||||
|
|
||||||
> **Status:** Proposed
|
|
||||||
> **Owner:** Platform team
|
|
||||||
> **Related:** Server authority + client prediction
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
This document specifies the multiplayer networking architecture for **agp-game**,
|
|
||||||
a Godot-based game built by autonomous agents. The architecture follows a
|
|
||||||
**server-authoritative model with client-side prediction and reconciliation**,
|
|
||||||
which is the industry standard for fast-paced, competitive multiplayer games.
|
|
||||||
|
|
||||||
The goals of this architecture are:
|
|
||||||
|
|
||||||
- **Fairness & anti-cheat:** The server is the single source of truth for all
|
|
||||||
gameplay state. Clients never directly mutate world state.
|
|
||||||
- **Responsiveness:** Client-side prediction hides network latency so local input
|
|
||||||
feels immediate.
|
|
||||||
- **Determinism:** The server runs a fixed-timestep simulation so that state is
|
|
||||||
reproducible and testable.
|
|
||||||
- **Scalability:** A clear separation between transport, simulation, and
|
|
||||||
replication layers allows the server to be tuned independently.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Transport Choice: ENet over WebSocket
|
|
||||||
|
|
||||||
### 2.1 Decision
|
|
||||||
|
|
||||||
We choose **ENet** as the primary transport for gameplay traffic.
|
|
||||||
|
|
||||||
### 2.2 Justification
|
|
||||||
|
|
||||||
| Criterion | ENet | WebSocket (TCP) |
|
|
||||||
|----------------------|----------------------------------------|-------------------------------------|
|
|
||||||
| **Reliability model**| Reliable + unreliable channels | Reliable only (TCP) |
|
|
||||||
| **Latency** | Low; unreliable packets skip retransmit| Head-of-line blocking on loss |
|
|
||||||
| **Packet ordering** | Per-channel ordering | Global strict ordering |
|
|
||||||
| **Congestion control**| Lightweight, game-oriented | TCP-style (slow start, backoff) |
|
|
||||||
| **Godot support** | First-class (`ENetConnection`, `MultiplayerPeerENet`) | Supported but TCP-based |
|
|
||||||
| **Use case fit** | Real-time action game | Chat, lobby, HTTP-style messaging |
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
|
|
||||||
- **Movement & state replication** are latency-sensitive and tolerate occasional
|
|
||||||
packet loss. ENet's *unreliable* channel lets us send position snapshots at high
|
|
||||||
frequency without head-of-line blocking.
|
|
||||||
- **RPCs that must be delivered** (e.g., interactions, spawns) use ENet's
|
|
||||||
*reliable* channel, giving us exactly the semantics we need without TCP's
|
|
||||||
retransmission stalls.
|
|
||||||
- Godot's `MultiplayerPeerENet` is mature and integrates directly with the
|
|
||||||
high-level multiplayer API (`MultiplayerAPI`, `rpc()`).
|
|
||||||
|
|
||||||
### 2.3 WebSocket as a Secondary Transport
|
|
||||||
|
|
||||||
WebSocket remains available as a **secondary transport** for:
|
|
||||||
|
|
||||||
- **Lobby / matchmaking** messaging (low-frequency, must-be-reliable).
|
|
||||||
- **Browser builds** where raw UDP/ENet is unavailable.
|
|
||||||
- **Admin / telemetry** channels.
|
|
||||||
|
|
||||||
The transport layer is abstracted behind an interface so gameplay code does not
|
|
||||||
depend on the underlying protocol.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Server-Side Game Loop
|
|
||||||
|
|
||||||
### 3.1 Tick Rate
|
|
||||||
|
|
||||||
- **Simulation tick rate:** **30 Hz** (33.33 ms per tick).
|
|
||||||
- **Replication / snapshot rate:** **30 Hz**, aligned with the simulation tick.
|
|
||||||
|
|
||||||
**Justification:**
|
|
||||||
|
|
||||||
- 30 Hz is sufficient for smooth movement and interaction in a top-down / 2D
|
|
||||||
action game while keeping CPU and bandwidth costs predictable.
|
|
||||||
- A fixed timestep (rather than delta-time) makes the simulation deterministic
|
|
||||||
and testable.
|
|
||||||
- The tick rate is a **configuration constant** so it can be raised (e.g., to
|
|
||||||
60 Hz) for competitive modes without architectural changes.
|
|
||||||
|
|
||||||
### 3.2 Authority Model
|
|
||||||
|
|
||||||
- **Server is authoritative** for:
|
|
||||||
- Player position, velocity, and physics state.
|
|
||||||
- Health, damage, and death.
|
|
||||||
- Item pickups, inventory, and world-object state.
|
|
||||||
- Spawning and despawning of entities.
|
|
||||||
- Game rules, scoring, and win/lose conditions.
|
|
||||||
- **Client is authoritative** for:
|
|
||||||
- Its own *input* (which keys/buttons are pressed).
|
|
||||||
- Local camera and UI.
|
|
||||||
- Cosmetic / non-gameplay presentation.
|
|
||||||
|
|
||||||
### 3.3 Server Loop Pseudocode
|
|
||||||
|
|
||||||
```
|
|
||||||
while server_running:
|
|
||||||
process_network_inbound() # read client inputs & RPCs
|
|
||||||
for _ in range(ticks_to_advance):
|
|
||||||
simulate_tick() # fixed 30 Hz step
|
|
||||||
broadcast_snapshots() # replicate authoritative state
|
|
||||||
process_network_outbound() # flush reliable/unreliable channels
|
|
||||||
```
|
|
||||||
|
|
||||||
The server accumulates real elapsed time and advances the simulation in fixed
|
|
||||||
`TICK_DURATION` increments, decoupling simulation from frame rate.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. RPC Call Patterns
|
|
||||||
|
|
||||||
RPCs are grouped by direction and reliability. All gameplay RPCs are routed
|
|
||||||
through the high-level `MultiplayerAPI` with explicit `rpc_id` targeting.
|
|
||||||
|
|
||||||
### 4.1 Client → Server (Input & Requests)
|
|
||||||
|
|
||||||
| RPC | Channel | Payload | Notes |
|
|
||||||
|------------------------------|-----------|-------------------------------------------|-------|
|
|
||||||
| `request_move_input` | unreliable| `{ seq, input_state, timestamp }` | Batched per tick; drives prediction |
|
|
||||||
| `request_interact` | reliable | `{ target_id }` | Open door, pick up item, use object |
|
|
||||||
| `request_attack` | reliable | `{ target_id, aim_dir }` | Combat action |
|
|
||||||
| `request_join` | reliable | `{ player_name, profile }` | Session setup |
|
|
||||||
| `request_respawn` | reliable | `{}` | After death |
|
|
||||||
|
|
||||||
**Design notes:**
|
|
||||||
|
|
||||||
- **Input is batched** per client tick and sent with a monotonically increasing
|
|
||||||
`seq` so the server can detect gaps and the client can reconcile.
|
|
||||||
- **Interactions are reliable** because they are discrete, must-happen events
|
|
||||||
(opening a door, picking up an item). Losing them would corrupt world state.
|
|
||||||
|
|
||||||
### 4.2 Server → Client (State & Events)
|
|
||||||
|
|
||||||
| RPC | Channel | Payload | Notes |
|
|
||||||
|------------------------------|-----------|-------------------------------------------|-------|
|
|
||||||
| `snapshot_state` | unreliable| `{ tick, entities[], player_states[] }` | Periodic authoritative state |
|
|
||||||
| `spawn_entity` | reliable | `{ entity_id, type, transform, props }` | New entity enters world |
|
|
||||||
| `despawn_entity` | reliable | `{ entity_id, reason }` | Entity removed |
|
|
||||||
| `interact_result` | reliable | `{ request_seq, success, result }` | Acknowledges interaction |
|
|
||||||
| `damage_event` | reliable | `{ target_id, amount, source_id }` | Combat feedback |
|
|
||||||
| `game_event` | reliable | `{ type, payload }` | Score, win, round start/end |
|
|
||||||
|
|
||||||
### 4.3 Broadcast vs. Targeted
|
|
||||||
|
|
||||||
- **Broadcast (all clients):** `snapshot_state`, `spawn_entity`,
|
|
||||||
`despawn_entity`, `game_event`.
|
|
||||||
- **Targeted (single client):** `interact_result`, `damage_event` (to affected
|
|
||||||
players), and any player-private data.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Client-Side Prediction & Reconciliation
|
|
||||||
|
|
||||||
### 5.1 Prediction
|
|
||||||
|
|
||||||
- The client runs a **local copy of the movement simulation** using the same
|
|
||||||
physics constants as the server.
|
|
||||||
- When the player provides input, the client:
|
|
||||||
1. Applies the input to its local player immediately.
|
|
||||||
2. Renders the predicted position.
|
|
||||||
3. Sends the input to the server (batched, with `seq`).
|
|
||||||
|
|
||||||
### 5.2 Reconciliation
|
|
||||||
|
|
||||||
- The server sends authoritative `snapshot_state` at 30 Hz containing the
|
|
||||||
server's tick number and authoritative player positions.
|
|
||||||
- The client keeps a **ring buffer of predicted states** keyed by input `seq`.
|
|
||||||
- On receiving a snapshot:
|
|
||||||
1. Find the last predicted state that matches the server's tick.
|
|
||||||
2. Compute the **error** between predicted and authoritative position.
|
|
||||||
3. If error exceeds a threshold, **snap or smoothly interpolate** the local
|
|
||||||
player to the authoritative position (error correction).
|
|
||||||
4. Re-simulate any inputs that occurred after the server's tick (rollback).
|
|
||||||
|
|
||||||
### 5.3 Interpolation of Remote Entities
|
|
||||||
|
|
||||||
- **Local player:** predicted + reconciled (see above).
|
|
||||||
- **Remote players / entities:** rendered with **interpolation delay** of
|
|
||||||
`2 × TICK_DURATION` (≈ 66 ms) to smooth out snapshot jitter.
|
|
||||||
- The client buffers the last N snapshots and interpolates between them.
|
|
||||||
|
|
||||||
### 5.4 Prediction Buffer Sizing
|
|
||||||
|
|
||||||
- Buffer size is adaptive based on measured RTT.
|
|
||||||
- Default: hold up to `ceil(RTT / TICK_DURATION) + 2` predicted states.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Entity & World State Replication
|
|
||||||
|
|
||||||
### 6.1 Entity Model
|
|
||||||
|
|
||||||
Every networked entity has:
|
|
||||||
|
|
||||||
- A globally unique `entity_id` (server-assigned).
|
|
||||||
- An `EntityType` (player, enemy, item, projectile, door, ...).
|
|
||||||
- A `Transform` (position, rotation).
|
|
||||||
- A typed `props` dictionary of gameplay state (health, state machine, etc.).
|
|
||||||
|
|
||||||
### 6.2 Snapshot Format
|
|
||||||
|
|
||||||
```
|
|
||||||
snapshot_state:
|
|
||||||
tick: uint32
|
|
||||||
entities:
|
|
||||||
- entity_id: uint32
|
|
||||||
type: uint8
|
|
||||||
transform: { x, y, rot }
|
|
||||||
props: { ... } # delta-encoded where possible
|
|
||||||
player_states:
|
|
||||||
- peer_id: int
|
|
||||||
entity_id: uint32
|
|
||||||
health: int
|
|
||||||
state: uint8
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.3 Delta Compression
|
|
||||||
|
|
||||||
- Only **changed** entity fields are sent per snapshot (dirty-flag per entity).
|
|
||||||
- Static or unchanged entities are omitted from the snapshot.
|
|
||||||
- This keeps bandwidth proportional to *activity*, not world size.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Connection & Session Lifecycle
|
|
||||||
|
|
||||||
1. **Connect:** Client opens an ENet connection to the server.
|
|
||||||
2. **Authenticate / Join:** Client sends `request_join`; server validates and
|
|
||||||
assigns a `peer_id` and spawns the player entity.
|
|
||||||
3. **Spawn:** Server broadcasts `spawn_entity` for the new player to all clients.
|
|
||||||
4. **Play:** Input → prediction → server simulation → snapshot → reconciliation.
|
|
||||||
5. **Disconnect:** Server removes the player entity, broadcasts `despawn_entity`,
|
|
||||||
and cleans up session state.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Security & Anti-Cheat
|
|
||||||
|
|
||||||
- **No client-authoritative gameplay values.** Clients only send *inputs* and
|
|
||||||
*requests*; the server computes all outcomes.
|
|
||||||
- **Input validation:** Server clamps movement speed, rejects out-of-bounds
|
|
||||||
positions, and validates interaction targets.
|
|
||||||
- **Rate limiting:** Per-peer input and RPC rate limits prevent flooding.
|
|
||||||
- **Sequence validation:** Gaps or replays in input `seq` are detected and
|
|
||||||
rejected.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Testing & Determinism
|
|
||||||
|
|
||||||
- The simulation is a **pure function of (state, inputs, tick)** so it can be
|
|
||||||
unit-tested headlessly.
|
|
||||||
- A **replay system** records inputs and can re-simulate to verify server and
|
|
||||||
client produce identical results.
|
|
||||||
- Network code is tested with a **mock transport** that can inject latency,
|
|
||||||
jitter, and packet loss.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Open Questions / Future Work
|
|
||||||
|
|
||||||
- **Interest management / spatial partitioning:** For large worlds, restrict
|
|
||||||
snapshots to entities near each client (AOI culling).
|
|
||||||
- **Server-side physics:** Decide whether to use Godot's physics server on the
|
|
||||||
host or a custom deterministic physics step.
|
|
||||||
- **Dedicated server vs. listen server:** The architecture supports both; a
|
|
||||||
dedicated headless server is the target for production.
|
|
||||||
- **WebSocket fallback:** Implement the transport abstraction for browser builds.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. Summary
|
|
||||||
|
|
||||||
| Concern | Decision |
|
|
||||||
|------------------------|-------------------------------------------------|
|
|
||||||
| Transport | ENet (primary), WebSocket (secondary) |
|
|
||||||
| Tick rate | 30 Hz fixed timestep |
|
|
||||||
| Authority | Server-authoritative; client sends input only |
|
|
||||||
| Prediction | Client-side prediction + reconciliation |
|
|
||||||
| Remote interpolation | 2-tick interpolation delay |
|
|
||||||
| Replication | Delta-compressed snapshots at 30 Hz |
|
|
||||||
| Interaction RPCs | Reliable channel |
|
|
||||||
| Movement input | Unreliable channel, batched with sequence |
|
|
||||||
@@ -1,737 +0,0 @@
|
|||||||
# World Chunk Data Format & Persistence Architecture
|
|
||||||
|
|
||||||
> **Status:** Proposed
|
|
||||||
> **Owner:** Platform team
|
|
||||||
> **Related:** Server authority + client prediction, avatar component system, content moderation & age verification, backend auth (JWT)
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
This document specifies the **world chunk data format** and **persistence
|
|
||||||
schema** for **agp-game**, a Godot-based multiplayer game built by autonomous
|
|
||||||
agents. It defines:
|
|
||||||
|
|
||||||
- The **chunk data format** — both a human-readable **JSON** form (for
|
|
||||||
authoring, tooling, and debugging) and a compact **binary** form (for
|
|
||||||
runtime loading and network transfer).
|
|
||||||
- The **SQLite schema** that persists world state on the server, including
|
|
||||||
chunk metadata, chunk payloads, and the world/room hierarchy.
|
|
||||||
- The **read/write API** that the server and client use to load, save, and
|
|
||||||
stream chunks.
|
|
||||||
|
|
||||||
The goal is a **single, versioned chunk contract** that is shared across the
|
|
||||||
Godot client, the Python backend, and the persistence layer. A chunk is the
|
|
||||||
atomic unit of world geometry, gameplay objects, and persistence — the server
|
|
||||||
loads and saves whole chunks, and clients stream the chunks around them.
|
|
||||||
|
|
||||||
### 1.1 Design Goals
|
|
||||||
|
|
||||||
- **Versioned & forward-compatible:** Every chunk carries a format version so
|
|
||||||
the loader can migrate old data and reject unknown future data gracefully.
|
|
||||||
- **Dual representation:** JSON for authoring/debugging, binary for
|
|
||||||
runtime/network. Both encode the *same* logical model so there is exactly one
|
|
||||||
source of truth for the schema.
|
|
||||||
- **Server-authoritative persistence:** The server is the only writer to the
|
|
||||||
SQLite store. Clients submit *edits* (deltas) and the server applies and
|
|
||||||
persists them, mirroring the server-authoritative networking model.
|
|
||||||
- **Chunk-granular persistence:** Persistence happens at chunk granularity so
|
|
||||||
the server can save a dirty chunk without rewriting the whole world, and can
|
|
||||||
stream only the chunks a client needs.
|
|
||||||
- **Deterministic & testable:** The binary format is byte-stable for a given
|
|
||||||
logical payload, enabling checksums, caching, and reproducible tests.
|
|
||||||
- **Moderation-aware:** Chunks reference content (assets, scripts) that carry
|
|
||||||
content flags (see `content_moderation.md`); the persistence layer stores the
|
|
||||||
moderation state alongside chunk data so enforcement can happen at load time.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. World Model & Chunking
|
|
||||||
|
|
||||||
### 2.1 World Hierarchy
|
|
||||||
|
|
||||||
The world is organized as a hierarchy that matches the moderation content graph:
|
|
||||||
|
|
||||||
```
|
|
||||||
World
|
|
||||||
└── Room
|
|
||||||
└── Chunk (the atomic persistence & streaming unit)
|
|
||||||
├── Tiles / Terrain
|
|
||||||
├── Static objects (props, geometry)
|
|
||||||
├── Dynamic objects (spawnable entities, interactables)
|
|
||||||
└── Metadata (flags, version, timestamps)
|
|
||||||
```
|
|
||||||
|
|
||||||
- A **World** is the top-level container (a named, versioned space).
|
|
||||||
- A **Room** is a bounded region within a world (a level, a building, a zone).
|
|
||||||
- A **Chunk** is a fixed-size, axis-aligned region of a room. It is the unit of
|
|
||||||
load, save, and stream.
|
|
||||||
|
|
||||||
### 2.2 Chunk Dimensions
|
|
||||||
|
|
||||||
Chunks are **fixed-size, axis-aligned boxes** in world space. The default
|
|
||||||
dimensions are a configuration constant so they can be tuned per world:
|
|
||||||
|
|
||||||
| Constant | Default | Description |
|
|
||||||
|---------------------|---------|----------------------------------------------------|
|
|
||||||
| `CHUNK_SIZE_X` | 32 | Chunk width in world units (tiles). |
|
|
||||||
| `CHUNK_SIZE_Y` | 32 | Chunk height in world units (tiles). |
|
|
||||||
| `CHUNK_SIZE_Z` | 1 | Chunk depth (1 = flat 2D world; >1 = volumetric). |
|
|
||||||
| `CHUNK_ORIGIN` | `(0,0)` | World-space origin of chunk coordinate `(0,0)`. |
|
|
||||||
|
|
||||||
A chunk is identified by its **integer chunk coordinate** `(cx, cy, cz)`,
|
|
||||||
computed from a world-space position `p` as:
|
|
||||||
|
|
||||||
```
|
|
||||||
cx = floor((p.x - CHUNK_ORIGIN.x) / CHUNK_SIZE_X)
|
|
||||||
cy = floor((p.y - CHUNK_ORIGIN.y) / CHUNK_SIZE_Y)
|
|
||||||
cz = floor((p.z - CHUNK_ORIGIN.z) / CHUNK_SIZE_Z)
|
|
||||||
```
|
|
||||||
|
|
||||||
The chunk's world-space bounding box is therefore:
|
|
||||||
|
|
||||||
```
|
|
||||||
min = (CHUNK_ORIGIN.x + cx*CHUNK_SIZE_X, ...)
|
|
||||||
max = min + (CHUNK_SIZE_X, CHUNK_SIZE_Y, CHUNK_SIZE_Z)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.3 Chunk Coordinate Key
|
|
||||||
|
|
||||||
For storage and lookup, a chunk is addressed by a **canonical string key**:
|
|
||||||
|
|
||||||
```
|
|
||||||
"{world_id}:{room_id}:{cx}:{cy}:{cz}"
|
|
||||||
```
|
|
||||||
|
|
||||||
Example: `"w_0001:r_0001:12:-4:0"`. This key is the primary lookup key in the
|
|
||||||
SQLite `chunks` table and is used in the read/write API.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Chunk Data Format
|
|
||||||
|
|
||||||
### 3.1 Logical Model
|
|
||||||
|
|
||||||
Both the JSON and binary encodings serialize the same logical chunk model. The
|
|
||||||
logical model is defined here once; the two encodings are projections of it.
|
|
||||||
|
|
||||||
```
|
|
||||||
Chunk
|
|
||||||
├── version : uint (format version, currently 1)
|
|
||||||
├── key : string (canonical chunk key, see §2.3)
|
|
||||||
├── world_id : string
|
|
||||||
├── room_id : string
|
|
||||||
├── coord : { cx, cy, cz } (int)
|
|
||||||
├── bounds : { min_x, min_y, min_z, max_x, max_y, max_z } (float)
|
|
||||||
├── tiles : TileLayer[] (terrain / tile data)
|
|
||||||
├── objects : WorldObject[] (static + dynamic objects)
|
|
||||||
├── flags : ContentFlags (moderation flags, see §3.5)
|
|
||||||
├── meta : { created_at, updated_at, revision, author }
|
|
||||||
└── checksum : string (SHA-256 of canonical payload)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 Tile Layer
|
|
||||||
|
|
||||||
A chunk's terrain is stored as one or more **tile layers**. Each layer is a
|
|
||||||
dense grid of tile IDs of size `CHUNK_SIZE_X × CHUNK_SIZE_Y` (× `CHUNK_SIZE_Z`
|
|
||||||
for volumetric worlds).
|
|
||||||
|
|
||||||
```
|
|
||||||
TileLayer
|
|
||||||
├── name : string (e.g. "ground", "walls", "decor")
|
|
||||||
├── layer_id : uint
|
|
||||||
├── width : uint (= CHUNK_SIZE_X)
|
|
||||||
├── height : uint (= CHUNK_SIZE_Y)
|
|
||||||
├── depth : uint (= CHUNK_SIZE_Z)
|
|
||||||
├── tiles : uint[] (flattened tile IDs, row-major, length = w*h*d)
|
|
||||||
└── palette : TileDef[] (tile ID → tile definition, shared per layer)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Tile encoding:** A tile ID is a `uint16` index into the layer's `palette`.
|
|
||||||
`0` is reserved for "empty/air". The palette maps each tile ID to a `TileDef`:
|
|
||||||
|
|
||||||
```
|
|
||||||
TileDef
|
|
||||||
├── id : uint16
|
|
||||||
├── asset_id : string (reference to a tile/terrain asset)
|
|
||||||
├── solid : bool (collision)
|
|
||||||
├── flags : uint32 (bitmask: walkable, climbable, liquid, ...)
|
|
||||||
└── variants : uint8 (number of visual variants for this tile)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rationale for palette + indices:** Storing dense `uint16` indices rather than
|
|
||||||
full asset strings per cell keeps the binary payload small (2 bytes/cell) while
|
|
||||||
the palette (shared across the layer) carries the rich per-tile metadata.
|
|
||||||
|
|
||||||
### 3.3 World Objects
|
|
||||||
|
|
||||||
Objects are the non-tile entities in a chunk: static props, interactables,
|
|
||||||
spawn points, and dynamic-object templates.
|
|
||||||
|
|
||||||
```
|
|
||||||
WorldObject
|
|
||||||
├── id : string (stable object id, unique within the chunk)
|
|
||||||
├── type : string (e.g. "prop", "interactable", "spawn_point", "door")
|
|
||||||
├── asset_id : string (reference to the object's mesh/glTF asset)
|
|
||||||
├── transform : { pos: [x,y,z], rot: [x,y,z,w], scale: [x,y,z] }
|
|
||||||
├── properties : object (type-specific key/value map, JSON-typed)
|
|
||||||
├── dynamic : bool (true if this is a spawnable dynamic entity)
|
|
||||||
└── flags : ContentFlags (per-object moderation flags)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Dynamic objects** are stored as *templates* in the chunk. Their *runtime
|
|
||||||
state* (position, health, inventory) is **not** stored in the chunk; it lives
|
|
||||||
in the runtime entity store and is persisted separately (see §4.4). This keeps
|
|
||||||
chunks stable and diffable — a chunk only changes when its *static* content
|
|
||||||
changes.
|
|
||||||
|
|
||||||
### 3.4 Content Flags
|
|
||||||
|
|
||||||
Each chunk (and each object) carries a **content flag set** that is the
|
|
||||||
aggregate of the moderation flags of the assets and scripts it references. This
|
|
||||||
mirrors the aggregation rules in `content_moderation.md`:
|
|
||||||
|
|
||||||
```
|
|
||||||
ContentFlags
|
|
||||||
├── categories : { violence, sexual, language, substance, gambling, horror, hate, custom }
|
|
||||||
│ (each → severity: none|mild|moderate|severe)
|
|
||||||
├── mature : bool (true if any contributing item is mature)
|
|
||||||
└── sources : string[] (flag ids that contributed, for audit)
|
|
||||||
```
|
|
||||||
|
|
||||||
The server computes and persists these flags at write time so that enforcement
|
|
||||||
(age gating, content filtering) can happen at load time without re-scanning
|
|
||||||
assets.
|
|
||||||
|
|
||||||
### 3.5 JSON Encoding
|
|
||||||
|
|
||||||
The JSON encoding is the **authoring and debugging** representation. It is
|
|
||||||
human-readable, diffable, and used by tools and tests. It is the canonical
|
|
||||||
logical model serialized directly.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"version": 1,
|
|
||||||
"key": "w_0001:r_0001:12:-4:0",
|
|
||||||
"world_id": "w_0001",
|
|
||||||
"room_id": "r_0001",
|
|
||||||
"coord": { "cx": 12, "cy": -4, "cz": 0 },
|
|
||||||
"bounds": { "min_x": 384.0, "min_y": -128.0, "min_z": 0.0,
|
|
||||||
"max_x": 416.0, "max_y": -96.0, "max_z": 1.0 },
|
|
||||||
"tiles": [
|
|
||||||
{
|
|
||||||
"name": "ground",
|
|
||||||
"layer_id": 0,
|
|
||||||
"width": 32,
|
|
||||||
"height": 32,
|
|
||||||
"depth": 1,
|
|
||||||
"palette": [
|
|
||||||
{ "id": 0, "asset_id": "", "solid": false, "flags": 0, "variants": 1 },
|
|
||||||
{ "id": 1, "asset_id": "tiles/grass", "solid": false, "flags": 1, "variants": 4 }
|
|
||||||
],
|
|
||||||
"tiles": [0, 1, 1, 1, 0, 1, 1, 0, 0, 1, 1, 1, 1, 0, 1, 1]
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"objects": [
|
|
||||||
{
|
|
||||||
"id": "obj_0001",
|
|
||||||
"type": "interactable",
|
|
||||||
"asset_id": "props/chest",
|
|
||||||
"transform": { "pos": [400.0, -110.0, 0.0],
|
|
||||||
"rot": [0.0, 0.0, 0.0, 1.0],
|
|
||||||
"scale": [1.0, 1.0, 1.0] },
|
|
||||||
"properties": { "loot_table": "chest_basic", "locked": false },
|
|
||||||
"dynamic": false,
|
|
||||||
"flags": { "categories": { "violence": "none" }, "mature": false, "sources": [] }
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"flags": { "categories": { "violence": "none" }, "mature": false, "sources": [] },
|
|
||||||
"meta": { "created_at": "2026-08-17T00:00:00Z",
|
|
||||||
"updated_at": "2026-08-17T00:00:00Z",
|
|
||||||
"revision": 3,
|
|
||||||
"author": "agent-bot" },
|
|
||||||
"checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note on the example checksum:** The value shown above is illustrative only.
|
|
||||||
> In practice the `checksum` field is the SHA-256 of the canonical binary
|
|
||||||
> payload body (see §3.6.3), not of the JSON text. The value here is a
|
|
||||||
> placeholder for documentation purposes.
|
|
||||||
|
|
||||||
### 3.6 Binary Encoding
|
|
||||||
|
|
||||||
The binary encoding is the **runtime and network** representation. It is compact
|
|
||||||
and byte-stable. It uses a simple, explicitly-specified layout (no external
|
|
||||||
serialization library) so it can be produced and consumed identically by the
|
|
||||||
Godot client (GDScript) and the Python backend.
|
|
||||||
|
|
||||||
#### 3.6.1 Header
|
|
||||||
|
|
||||||
| Offset | Size | Field | Type / Encoding |
|
|
||||||
|--------|------|--------------|------------------------------------------|
|
|
||||||
| 0 | 4 | magic | ASCII `"AGPC"` (0x41 0x47 0x50 0x43) |
|
|
||||||
| 4 | 2 | version | `uint16` LE (currently `1`) |
|
|
||||||
| 6 | 2 | header_len | `uint16` LE (bytes of header after this) |
|
|
||||||
| 8 | 4 | flags | `uint32` LE (bitmask, reserved) |
|
|
||||||
| 12 | 4 | payload_len | `uint32` LE (bytes of payload body) |
|
|
||||||
| 16 | 32 | checksum | SHA-256 of payload body (hex, 32 bytes) |
|
|
||||||
|
|
||||||
Total header size: **48 bytes**.
|
|
||||||
|
|
||||||
#### 3.6.2 Payload Body
|
|
||||||
|
|
||||||
The payload body is a sequence of typed sections. Each section has a small
|
|
||||||
header:
|
|
||||||
|
|
||||||
| Offset | Size | Field | Type / Encoding |
|
|
||||||
|--------|------|------------|----------------------------|
|
|
||||||
| 0 | 1 | section_id | `uint8` (see table below) |
|
|
||||||
| 1 | 4 | section_len| `uint32` LE (bytes of section data) |
|
|
||||||
| 5 | ... | data | section-specific |
|
|
||||||
|
|
||||||
Section IDs:
|
|
||||||
|
|
||||||
| section_id | Section | Data layout |
|
|
||||||
|------------|----------------|-------------------------------------------------------------------|
|
|
||||||
| `0x01` | metadata | world_id, room_id (length-prefixed strings), coord (3×int32), bounds (6×float32) |
|
|
||||||
| `0x02` | tile layer | name, layer_id, dims (3×uint16), palette, dense tile indices |
|
|
||||||
| `0x03` | object | one `WorldObject` (repeated; one section per object) |
|
|
||||||
| `0x04` | content flags | category severities (8×uint8), mature (uint8), sources (string list) |
|
|
||||||
| `0x05` | meta | created_at, updated_at (int64 unix), revision (uint32), author (string) |
|
|
||||||
|
|
||||||
**String encoding:** length-prefixed UTF-8 — `uint16` LE byte length followed by
|
|
||||||
the UTF-8 bytes.
|
|
||||||
|
|
||||||
**Tile layer data layout (section `0x02`):**
|
|
||||||
|
|
||||||
```
|
|
||||||
name : string
|
|
||||||
layer_id : uint16 LE
|
|
||||||
width : uint16 LE
|
|
||||||
height : uint16 LE
|
|
||||||
depth : uint16 LE
|
|
||||||
palette_count : uint16 LE
|
|
||||||
palette : palette_count × TileDef
|
|
||||||
tile_count : uint32 LE
|
|
||||||
tiles : tile_count × uint16 LE (dense, row-major)
|
|
||||||
```
|
|
||||||
|
|
||||||
```
|
|
||||||
TileDef:
|
|
||||||
id : uint16 LE
|
|
||||||
asset_id : string
|
|
||||||
solid : uint8
|
|
||||||
flags : uint32 LE
|
|
||||||
variants : uint8
|
|
||||||
```
|
|
||||||
|
|
||||||
**Object data layout (section `0x03`):**
|
|
||||||
|
|
||||||
```
|
|
||||||
id : string
|
|
||||||
type : string
|
|
||||||
asset_id : string
|
|
||||||
pos : 3 × float32
|
|
||||||
rot : 4 × float32
|
|
||||||
scale : 3 × float32
|
|
||||||
dynamic : uint8
|
|
||||||
properties : JSON string (length-prefixed)
|
|
||||||
flags : ContentFlags (see 0x04 layout)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Content flags layout (section `0x04`):**
|
|
||||||
|
|
||||||
```
|
|
||||||
violence, sexual, language, substance, gambling, horror, hate, custom
|
|
||||||
: 8 × uint8 (severity enum: 0=none,1=mild,2=moderate,3=severe)
|
|
||||||
mature : uint8
|
|
||||||
source_count: uint16 LE
|
|
||||||
sources : source_count × string
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3.6.3 Byte-Stability
|
|
||||||
|
|
||||||
For a given logical payload, the binary encoding is **deterministic**:
|
|
||||||
|
|
||||||
- All integers are little-endian.
|
|
||||||
- All strings are UTF-8, length-prefixed, and never null-terminated.
|
|
||||||
- Maps (e.g. `properties`) are serialized as a **canonical JSON string** with
|
|
||||||
keys sorted lexicographically.
|
|
||||||
- The `checksum` is the SHA-256 of the payload body bytes.
|
|
||||||
|
|
||||||
This guarantees that two encoders produce identical bytes, enabling content
|
|
||||||
addressing, caching, and reproducible tests.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. SQLite Persistence Schema
|
|
||||||
|
|
||||||
The server persists world state in a **SQLite** database. SQLite is chosen for
|
|
||||||
its zero-configuration, single-file, transactional, and embedded nature — ideal
|
|
||||||
for a server that owns the world store and needs ACID guarantees without a
|
|
||||||
separate database process.
|
|
||||||
|
|
||||||
### 4.1 Database Layout
|
|
||||||
|
|
||||||
The database file is `world.db` (path configurable). It contains the following
|
|
||||||
tables:
|
|
||||||
|
|
||||||
```
|
|
||||||
worlds
|
|
||||||
rooms
|
|
||||||
chunks
|
|
||||||
chunk_objects
|
|
||||||
content_flags
|
|
||||||
revisions
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 `worlds`
|
|
||||||
|
|
||||||
Top-level world containers.
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE worlds (
|
|
||||||
id TEXT PRIMARY KEY, -- e.g. 'w_0001'
|
|
||||||
name TEXT NOT NULL,
|
|
||||||
description TEXT,
|
|
||||||
chunk_size_x INTEGER NOT NULL DEFAULT 32,
|
|
||||||
chunk_size_y INTEGER NOT NULL DEFAULT 32,
|
|
||||||
chunk_size_z INTEGER NOT NULL DEFAULT 1,
|
|
||||||
origin_x REAL NOT NULL DEFAULT 0,
|
|
||||||
origin_y REAL NOT NULL DEFAULT 0,
|
|
||||||
origin_z REAL NOT NULL DEFAULT 0,
|
|
||||||
created_at TEXT NOT NULL, -- ISO-8601 UTC
|
|
||||||
updated_at TEXT NOT NULL
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.3 `rooms`
|
|
||||||
|
|
||||||
Rooms within a world.
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE rooms (
|
|
||||||
id TEXT PRIMARY KEY, -- e.g. 'r_0001'
|
|
||||||
world_id TEXT NOT NULL REFERENCES worlds(id) ON DELETE CASCADE,
|
|
||||||
name TEXT NOT NULL,
|
|
||||||
bounds_min_x REAL NOT NULL,
|
|
||||||
bounds_min_y REAL NOT NULL,
|
|
||||||
bounds_min_z REAL NOT NULL DEFAULT 0,
|
|
||||||
bounds_max_x REAL NOT NULL,
|
|
||||||
bounds_max_y REAL NOT NULL,
|
|
||||||
bounds_max_z REAL NOT NULL DEFAULT 1,
|
|
||||||
created_at TEXT NOT NULL,
|
|
||||||
updated_at TEXT NOT NULL,
|
|
||||||
UNIQUE (world_id, name)
|
|
||||||
);
|
|
||||||
CREATE INDEX idx_rooms_world ON rooms(world_id);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.4 `chunks`
|
|
||||||
|
|
||||||
The core persistence table. One row per chunk. The **payload** is stored as a
|
|
||||||
BLOB in the **binary format** (§3.6); the JSON form is derived on demand for
|
|
||||||
authoring/debugging and is not stored (to avoid dual-write drift).
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE chunks (
|
|
||||||
key TEXT PRIMARY KEY, -- canonical key 'world:room:cx:cy:cz'
|
|
||||||
world_id TEXT NOT NULL REFERENCES worlds(id) ON DELETE CASCADE,
|
|
||||||
room_id TEXT NOT NULL REFERENCES rooms(id) ON DELETE CASCADE,
|
|
||||||
cx INTEGER NOT NULL,
|
|
||||||
cy INTEGER NOT NULL,
|
|
||||||
cz INTEGER NOT NULL DEFAULT 0,
|
|
||||||
format_version INTEGER NOT NULL DEFAULT 1,
|
|
||||||
payload BLOB NOT NULL, -- binary chunk encoding (§3.6)
|
|
||||||
payload_len INTEGER NOT NULL,
|
|
||||||
checksum TEXT NOT NULL, -- SHA-256 of payload
|
|
||||||
revision INTEGER NOT NULL DEFAULT 0,
|
|
||||||
dirty INTEGER NOT NULL DEFAULT 0, -- 1 = needs flush to disk
|
|
||||||
created_at TEXT NOT NULL,
|
|
||||||
updated_at TEXT NOT NULL,
|
|
||||||
UNIQUE (world_id, room_id, cx, cy, cz)
|
|
||||||
);
|
|
||||||
CREATE INDEX idx_chunks_world_room ON chunks(world_id, room_id);
|
|
||||||
CREATE INDEX idx_chunks_coord ON chunks(cx, cy, cz);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Design notes:**
|
|
||||||
|
|
||||||
- The `payload` BLOB is the single source of truth for chunk content. The
|
|
||||||
`checksum` guards against corruption and enables content addressing.
|
|
||||||
- `revision` increments on every write; it is used for optimistic concurrency
|
|
||||||
and change detection (see §5.4).
|
|
||||||
- `dirty` marks chunks that have been modified in memory but not yet flushed,
|
|
||||||
enabling a write-behind persistence strategy (see §5.5).
|
|
||||||
|
|
||||||
### 4.5 `chunk_objects`
|
|
||||||
|
|
||||||
A denormalized, queryable index of the objects inside each chunk. This is
|
|
||||||
**derived** from the chunk payload and kept in sync by the write path. It exists
|
|
||||||
so the server can answer queries like "which chunks contain a door?" without
|
|
||||||
parsing every payload BLOB.
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE chunk_objects (
|
|
||||||
id TEXT NOT NULL, -- object id (unique within chunk)
|
|
||||||
chunk_key TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
|
|
||||||
type TEXT NOT NULL, -- 'prop', 'interactable', ...
|
|
||||||
asset_id TEXT,
|
|
||||||
dynamic INTEGER NOT NULL DEFAULT 0,
|
|
||||||
pos_x REAL NOT NULL,
|
|
||||||
pos_y REAL NOT NULL,
|
|
||||||
pos_z REAL NOT NULL DEFAULT 0,
|
|
||||||
PRIMARY KEY (chunk_key, id)
|
|
||||||
);
|
|
||||||
CREATE INDEX idx_chunk_objects_type ON chunk_objects(type);
|
|
||||||
CREATE INDEX idx_chunk_objects_asset ON chunk_objects(asset_id);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Sync mechanism:** `chunk_objects` is maintained **explicitly by the write
|
|
||||||
path** — it is not a SQL trigger. Whenever `put_chunk` (or `delete_chunk`)
|
|
||||||
commits a chunk, the service layer performs a **delete-and-reinsert** of that
|
|
||||||
chunk's object rows in the same transaction: it deletes all rows for
|
|
||||||
`chunk_key`, then inserts fresh rows parsed from the new payload. This keeps the
|
|
||||||
index transactionally consistent with the payload and avoids the complexity and
|
|
||||||
fragility of SQL triggers over a binary BLOB. Because the index is derived, it
|
|
||||||
can always be rebuilt from `chunks.payload` if it ever drifts (a `rebuild_index`
|
|
||||||
utility is provided for this).
|
|
||||||
|
|
||||||
### 4.6 `content_flags`
|
|
||||||
|
|
||||||
Persists the aggregated moderation flags per chunk (and optionally per object).
|
|
||||||
This lets the server enforce age/content gates at load time without parsing
|
|
||||||
payloads.
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE content_flags (
|
|
||||||
chunk_key TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
|
|
||||||
object_id TEXT NOT NULL DEFAULT '', -- '' = chunk-level flag (sentinel)
|
|
||||||
violence INTEGER NOT NULL DEFAULT 0,
|
|
||||||
sexual INTEGER NOT NULL DEFAULT 0,
|
|
||||||
language INTEGER NOT NULL DEFAULT 0,
|
|
||||||
substance INTEGER NOT NULL DEFAULT 0,
|
|
||||||
gambling INTEGER NOT NULL DEFAULT 0,
|
|
||||||
horror INTEGER NOT NULL DEFAULT 0,
|
|
||||||
hate INTEGER NOT NULL DEFAULT 0,
|
|
||||||
custom INTEGER NOT NULL DEFAULT 0,
|
|
||||||
mature INTEGER NOT NULL DEFAULT 0,
|
|
||||||
sources TEXT NOT NULL DEFAULT '[]', -- JSON array of flag ids
|
|
||||||
PRIMARY KEY (chunk_key, object_id)
|
|
||||||
);
|
|
||||||
CREATE INDEX idx_content_flags_mature ON content_flags(mature);
|
|
||||||
```
|
|
||||||
|
|
||||||
Severity is stored as `0=none, 1=mild, 2=moderate, 3=severe`.
|
|
||||||
|
|
||||||
**Chunk-level vs. object-level flags:** Chunk-level flags use the **sentinel
|
|
||||||
value `''` (empty string)** in `object_id` rather than `NULL`. This is
|
|
||||||
deliberate: in SQLite, `NULL` values in a composite primary key are **not**
|
|
||||||
unique-constrained, so two rows with the same `chunk_key` and `object_id = NULL`
|
|
||||||
could be inserted accidentally. Using `''` as the sentinel means the composite
|
|
||||||
`PRIMARY KEY (chunk_key, object_id)` enforces that there is **exactly one**
|
|
||||||
chunk-level flag row per chunk. Object-level flags use the object's actual `id`
|
|
||||||
(which is never empty). The application layer treats `object_id = ''` as
|
|
||||||
"chunk-level" and any non-empty value as "object-level".
|
|
||||||
|
|
||||||
### 4.7 `revisions`
|
|
||||||
|
|
||||||
An append-only audit log of chunk writes. Enables rollback, auditing, and
|
|
||||||
replication of changes.
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE revisions (
|
|
||||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
||||||
chunk_key TEXT NOT NULL, -- NOT a FK: survives chunk deletion
|
|
||||||
revision INTEGER NOT NULL,
|
|
||||||
actor TEXT NOT NULL, -- user / agent id
|
|
||||||
action TEXT NOT NULL, -- 'create' | 'update' | 'delete'
|
|
||||||
checksum TEXT NOT NULL, -- SHA-256 of payload
|
|
||||||
payload BLOB, -- full binary payload at this revision
|
|
||||||
created_at TEXT NOT NULL
|
|
||||||
);
|
|
||||||
CREATE INDEX idx_revisions_chunk ON revisions(chunk_key);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rollback support:** The `payload` BLOB stores the **full binary chunk payload**
|
|
||||||
at each revision. This is what makes rollback possible: to restore a chunk to a
|
|
||||||
previous revision, the server reads the `payload` of the target revision and
|
|
||||||
writes it back to `chunks.payload` (incrementing `revision` and appending a new
|
|
||||||
`revisions` row). Without the payload, only the checksum would be available,
|
|
||||||
which is insufficient to reconstruct the chunk.
|
|
||||||
|
|
||||||
**Audit trail preservation:** `chunk_key` is **not** a foreign key to `chunks`.
|
|
||||||
This means deleting a chunk does **not** cascade-delete its revision history —
|
|
||||||
the audit trail is preserved even after a chunk is removed. (The `chunk_key`
|
|
||||||
string is still stored so the history can be correlated to a chunk that existed
|
|
||||||
at that time.) If a chunk is later recreated with the same key, its history is
|
|
||||||
still intact.
|
|
||||||
|
|
||||||
### 4.8 Schema Versioning & Migrations
|
|
||||||
|
|
||||||
The database carries a schema version in a `meta` table:
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE meta (
|
|
||||||
key TEXT PRIMARY KEY,
|
|
||||||
value TEXT NOT NULL
|
|
||||||
);
|
|
||||||
-- seed: INSERT INTO meta(key, value) VALUES ('schema_version', '1');
|
|
||||||
```
|
|
||||||
|
|
||||||
Migrations are applied in order at startup. Each migration is a numbered SQL
|
|
||||||
script; the server tracks the applied version in `meta` and applies any pending
|
|
||||||
migrations transactionally. This keeps the schema forward-compatible as the
|
|
||||||
chunk format evolves.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Read/Write API
|
|
||||||
|
|
||||||
The API is exposed as a **Python service layer** on the backend (the same
|
|
||||||
process that owns the SQLite store) and consumed by the Godot client over the
|
|
||||||
network transport (see `networking.md`). The service layer is the **only**
|
|
||||||
writer to the database; clients never touch SQLite directly.
|
|
||||||
|
|
||||||
### 5.1 Service Interface (Python)
|
|
||||||
|
|
||||||
```python
|
|
||||||
class WorldStore:
|
|
||||||
"""Owns the SQLite connection and chunk read/write operations."""
|
|
||||||
|
|
||||||
def get_chunk(self, key: str) -> Chunk | None: ...
|
|
||||||
def get_chunk_binary(self, key: str) -> bytes | None: ...
|
|
||||||
def put_chunk(self, chunk: Chunk, actor: str) -> Chunk: ...
|
|
||||||
def delete_chunk(self, key: str, actor: str) -> None: ...
|
|
||||||
def list_chunks(self, world_id: str, room_id: str | None = None,
|
|
||||||
bounds: Bounds | None = None) -> list[str]: ...
|
|
||||||
def get_chunk_flags(self, key: str) -> ContentFlags: ...
|
|
||||||
def flush_dirty(self) -> int: ...
|
|
||||||
def rollback_chunk(self, key: str, revision: int, actor: str) -> Chunk: ...
|
|
||||||
def rebuild_index(self, chunk_key: str | None = None) -> int: ...
|
|
||||||
def migrate(self) -> None: ...
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.2 Encoding Helpers
|
|
||||||
|
|
||||||
The service layer provides symmetric encode/decode functions shared by the
|
|
||||||
client and server:
|
|
||||||
|
|
||||||
```python
|
|
||||||
def encode_binary(chunk: Chunk) -> bytes: ...
|
|
||||||
def decode_binary(data: bytes) -> Chunk: ...
|
|
||||||
def encode_json(chunk: Chunk) -> str: ...
|
|
||||||
def decode_json(text: str) -> Chunk: ...
|
|
||||||
def checksum(payload: bytes) -> str: ...
|
|
||||||
```
|
|
||||||
|
|
||||||
These are the single implementation of the format spec (§3), so the Godot
|
|
||||||
client and Python backend never drift.
|
|
||||||
|
|
||||||
### 5.3 Network RPCs
|
|
||||||
|
|
||||||
The chunk API is exposed to the client via RPCs (matching the networking
|
|
||||||
architecture). All chunk traffic is **reliable** (chunks are discrete,
|
|
||||||
must-arrive data).
|
|
||||||
|
|
||||||
| RPC | Direction | Payload | Notes |
|
|
||||||
|----------------------------|-----------|-------------------------------------------|-------|
|
|
||||||
| `request_chunk` | C → S | `{ key }` | Client asks for a chunk |
|
|
||||||
| `chunk_data` | S → C | `{ key, binary_payload, checksum }` | Server streams a chunk |
|
|
||||||
| `request_chunk_edit` | C → S | `{ key, base_revision, delta }` | Client submits an edit |
|
|
||||||
| `chunk_edit_result` | S → C | `{ key, success, new_revision, error? }` | Acknowledges an edit |
|
|
||||||
| `chunk_invalidated` | S → C | `{ key, new_revision }` | Server pushes a change |
|
|
||||||
| `request_chunk_flags` | C → S | `{ key }` | Age/content gate check |
|
|
||||||
|
|
||||||
### 5.4 Edit & Concurrency Model
|
|
||||||
|
|
||||||
- **Read:** Client requests a chunk; server returns the binary payload and its
|
|
||||||
`revision`.
|
|
||||||
- **Edit:** Client submits a **delta** against a known `base_revision`. The
|
|
||||||
server applies the delta, increments `revision`, persists, and returns the new
|
|
||||||
revision.
|
|
||||||
- **Optimistic concurrency:** If the chunk's current revision differs from the
|
|
||||||
client's `base_revision`, the server rejects the edit with a conflict error
|
|
||||||
and the client re-fetches and re-applies. This prevents lost updates when two
|
|
||||||
clients edit the same chunk.
|
|
||||||
- **Deltas:** A delta is a JSON patch (RFC 6902 style) applied to the chunk's
|
|
||||||
logical model. The server validates the patched chunk (schema, bounds,
|
|
||||||
moderation) before persisting.
|
|
||||||
|
|
||||||
### 5.5 Write-Behind Persistence
|
|
||||||
|
|
||||||
To amortize disk I/O, the server keeps a **dirty set** of chunks modified in
|
|
||||||
memory and flushes them to SQLite in batches:
|
|
||||||
|
|
||||||
1. `put_chunk` updates the in-memory chunk and marks it `dirty`.
|
|
||||||
2. A background flusher periodically calls `flush_dirty()`, which writes all
|
|
||||||
dirty chunks in a single transaction and clears the `dirty` flag.
|
|
||||||
3. On graceful shutdown, `flush_dirty()` is called to ensure durability.
|
|
||||||
|
|
||||||
This keeps the hot path (in-memory chunk access) fast while guaranteeing
|
|
||||||
durability at shutdown and on a configurable interval.
|
|
||||||
|
|
||||||
**Recovery after unclean shutdown:** The `dirty` column in the `chunks` table
|
|
||||||
exists specifically to support recovery if the process crashes before a flush
|
|
||||||
completes. On startup, the server scans for rows where `dirty = 1` and treats
|
|
||||||
them as **unflushed in-memory state that was lost** — it re-reads the last
|
|
||||||
persisted payload from `chunks.payload` (the last durable state) and clears the
|
|
||||||
`dirty` flag. In other words, `dirty = 1` at startup means "the last write was
|
|
||||||
not durable; discard the in-memory delta and fall back to the persisted
|
|
||||||
payload." This guarantees that the on-disk state is always a consistent,
|
|
||||||
previously-committed snapshot, never a partially-written chunk. (The in-memory
|
|
||||||
dirty set is authoritative during normal operation; the `dirty` column is only a
|
|
||||||
recovery marker.)
|
|
||||||
|
|
||||||
### 5.6 Streaming & Caching
|
|
||||||
|
|
||||||
- The server streams only the chunks a client needs (those within the client's
|
|
||||||
view radius), using `list_chunks` with a bounds query.
|
|
||||||
- Chunks are cached in memory (LRU) keyed by `key`; the cache is invalidated on
|
|
||||||
write.
|
|
||||||
- The binary payload is content-addressed by `checksum`, so unchanged chunks can
|
|
||||||
be served from cache without re-reading SQLite.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Format Versioning & Migration
|
|
||||||
|
|
||||||
- The chunk format `version` field (currently `1`) is checked on decode. A
|
|
||||||
decoder that encounters a higher version than it supports **rejects** the
|
|
||||||
chunk with a clear error rather than misreading it.
|
|
||||||
- The SQLite `schema_version` in `meta` drives database migrations (§4.8).
|
|
||||||
- Chunk payloads are migrated **lazily**: when a chunk is read and its
|
|
||||||
`format_version` is older than the current one, the server migrates it to the
|
|
||||||
current version in memory and marks it dirty so it is rewritten on the next
|
|
||||||
flush. This avoids a costly full-world migration at startup.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Security & Integrity
|
|
||||||
|
|
||||||
- **Server-authoritative writes:** Only the `WorldStore` writes to SQLite;
|
|
||||||
clients submit deltas that are validated before application.
|
|
||||||
- **Checksum verification:** Every chunk payload is checksummed (SHA-256) on
|
|
||||||
write and verified on read. Corruption is detected and the chunk is re-fetched
|
|
||||||
or flagged.
|
|
||||||
- **Bounds validation:** Chunk coordinates and object positions are validated
|
|
||||||
against the world's chunk dimensions and room bounds before persistence.
|
|
||||||
- **Moderation enforcement:** `content_flags` are checked at load time; mature
|
|
||||||
chunks are gated behind the age-verification flow (see `content_moderation.md`).
|
|
||||||
- **Input validation:** All string fields are length-limited and validated
|
|
||||||
against allowed character sets to prevent injection and oversized payloads.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Open Questions / Future Work
|
|
||||||
|
|
||||||
- **Volumetric worlds:** The schema and format already support `CHUNK_SIZE_Z >
|
|
||||||
1`, but the tooling and streaming for 3D chunks are not yet specified.
|
|
||||||
- **Chunk compression:** For very large worlds, the binary payload could be
|
|
||||||
compressed (e.g. zstd) before storage/transfer. The header reserves a `flags`
|
|
||||||
bitmask for a compression flag.
|
|
||||||
- **Multi-server sharding:** If a single SQLite file becomes a bottleneck, the
|
|
||||||
`chunks` table could be sharded by `world_id` across multiple databases. The
|
|
||||||
key design already supports this (world_id is a leading key component).
|
|
||||||
- **Delta compression for streaming:** Instead of sending full chunks, the
|
|
||||||
server could send only the delta between revisions to reduce bandwidth for
|
|
||||||
frequently-updated chunks.
|
|
||||||
+42
-4
@@ -6,11 +6,49 @@ config_version=5
|
|||||||
|
|
||||||
[application]
|
[application]
|
||||||
|
|
||||||
config/name="AGP Game"
|
config/name="AGP-Game"
|
||||||
run/main_scene="res://scenes/main.tscn"
|
run/main_scene="res://scenes/main_menu.tscn"
|
||||||
config/features=PackedStringArray("4.6.2")
|
config/features=PackedStringArray("4.6.2")
|
||||||
|
|
||||||
|
[autoload]
|
||||||
|
|
||||||
[display]
|
[display]
|
||||||
|
|
||||||
window/size/viewport_width=1280
|
window/size/viewport_width=1920
|
||||||
window/size/viewport_height=720
|
window/size/viewport_height=1080
|
||||||
|
window/stretch/mode="canvas_items"
|
||||||
|
|
||||||
|
[rendering]
|
||||||
|
|
||||||
|
renderer/rendering_method="gl_compatibility"
|
||||||
|
renderer/rendering_method.mobile="gl_compatibility"
|
||||||
|
|
||||||
|
[export]
|
||||||
|
|
||||||
|
[export_options]
|
||||||
|
|
||||||
|
name="AGP-Game"
|
||||||
|
|
||||||
|
[export_options/platform:windows_desktop]
|
||||||
|
|
||||||
|
bits_format=1
|
||||||
|
export_format=0
|
||||||
|
export_path=""
|
||||||
|
options="binary_format/relax_conformance=true"
|
||||||
|
|
||||||
|
[export_options/platform:linux/x11]
|
||||||
|
|
||||||
|
export_format=0
|
||||||
|
export_path=""
|
||||||
|
options="binary_format/relax_conformance=true"
|
||||||
|
|
||||||
|
[export_options/platform:mac_os]
|
||||||
|
|
||||||
|
export_format=0
|
||||||
|
export_path=""
|
||||||
|
options="binary_format/relax_conformance=true"
|
||||||
|
|
||||||
|
[export_options/platform:web]
|
||||||
|
|
||||||
|
export_format=0
|
||||||
|
export_path=""
|
||||||
|
|||||||
@@ -1,6 +0,0 @@
|
|||||||
[gd_scene load_steps=2 format=3 uid="uid://main_scene"]
|
|
||||||
|
|
||||||
[ext_resource type="Script" path="res://scripts/chunk_stream_manager.gd" id="1_chunk_stream"]
|
|
||||||
|
|
||||||
[node name="Main" type="Node3D"]
|
|
||||||
script = ExtResource("1_chunk_stream")
|
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
[gd_scene load_steps=2 format=3 uid="uid://main_menu"]
|
||||||
|
|
||||||
|
[ext_resource type="Script" path="res://scripts/main_menu.gd" id="1_main"]
|
||||||
|
|
||||||
|
[node name="MainMenu" type="Control"]
|
||||||
|
anchors_preset = 15
|
||||||
|
anchor_right = 1.0
|
||||||
|
anchor_bottom = 1.0
|
||||||
|
grow_horizontal = 2
|
||||||
|
grow_vertical = 2
|
||||||
|
script = ExtResource("1_main")
|
||||||
|
|
||||||
|
[node name="CenterContainer" type="CenterContainer" parent="."]
|
||||||
|
layout_mode = 3
|
||||||
|
anchors_preset = 15
|
||||||
|
anchor_right = 1.0
|
||||||
|
anchor_bottom = 1.0
|
||||||
|
grow_horizontal = 2
|
||||||
|
grow_vertical = 2
|
||||||
|
|
||||||
|
[node name="VBoxContainer" type="VBoxContainer" parent="CenterContainer"]
|
||||||
|
layout_mode = 1
|
||||||
|
theme_override_constants/separation = 16
|
||||||
|
size_flags_horizontal = 4
|
||||||
|
|
||||||
|
[node name="TitleLabel" type="Label" parent="CenterContainer/VBoxContainer"]
|
||||||
|
layout_mode = 1
|
||||||
|
text = "AGP Game"
|
||||||
|
horizontal_alignment = 1
|
||||||
|
theme_override_font_sizes/font_size = 72
|
||||||
|
|
||||||
|
[node name="PlayButton" type="Button" parent="CenterContainer/VBoxContainer"]
|
||||||
|
layout_mode = 1
|
||||||
|
text = "Play"
|
||||||
|
size_flags_horizontal = 4
|
||||||
|
|
||||||
|
[node name="QuitButton" type="Button" parent="CenterContainer/VBoxContainer"]
|
||||||
|
layout_mode = 1
|
||||||
|
text = "Quit"
|
||||||
|
size_flags_horizontal = 4
|
||||||
@@ -1,105 +0,0 @@
|
|||||||
class_name Chunk
|
|
||||||
extends Node3D
|
|
||||||
## A single world chunk. Holds the chunk coordinate, bounds, and the
|
|
||||||
## visual/gameplay content for that region of the world.
|
|
||||||
##
|
|
||||||
## Chunks are the atomic unit of world geometry, gameplay objects, and
|
|
||||||
## persistence (see docs/architecture/world.md). The server loads and saves
|
|
||||||
## whole chunks; clients stream the chunks around them.
|
|
||||||
|
|
||||||
## Default chunk dimensions in world units (tiles). Matches the constants in
|
|
||||||
## docs/architecture/world.md section 2.2.
|
|
||||||
const CHUNK_SIZE_X: int = 32
|
|
||||||
const CHUNK_SIZE_Y: int = 32
|
|
||||||
const CHUNK_SIZE_Z: int = 1
|
|
||||||
|
|
||||||
## World-space origin of chunk coordinate (0,0).
|
|
||||||
const CHUNK_ORIGIN := Vector3(0.0, 0.0, 0.0)
|
|
||||||
|
|
||||||
## Chunk coordinate (cx, cy, cz) in chunk space.
|
|
||||||
var coord := Vector3i.ZERO
|
|
||||||
|
|
||||||
## The canonical chunk key: "{world_id}:{room_id}:{cx}:{cy}:{cz}".
|
|
||||||
var key: String = ""
|
|
||||||
|
|
||||||
## World and room identifiers this chunk belongs to.
|
|
||||||
var world_id: String = ""
|
|
||||||
var room_id: String = ""
|
|
||||||
|
|
||||||
## Format version of the chunk payload (currently 1).
|
|
||||||
var format_version: int = 1
|
|
||||||
|
|
||||||
## Revision counter, incremented on every write. Used for optimistic
|
|
||||||
## concurrency and change detection.
|
|
||||||
var revision: int = 0
|
|
||||||
|
|
||||||
## Whether this chunk has been modified in memory but not yet flushed.
|
|
||||||
var dirty: bool = false
|
|
||||||
|
|
||||||
## Container for static objects (props, geometry) in this chunk.
|
|
||||||
var objects: Array[Node3D] = []
|
|
||||||
|
|
||||||
## Container for dynamic object templates (spawnable entities).
|
|
||||||
var dynamic_templates: Array[Node3D] = []
|
|
||||||
|
|
||||||
## The world-space bounding box of this chunk.
|
|
||||||
var bounds: AABB
|
|
||||||
|
|
||||||
|
|
||||||
func _init(p_coord: Vector3i = Vector3i.ZERO, p_world_id: String = "", p_room_id: String = "") -> void:
|
|
||||||
coord = p_coord
|
|
||||||
world_id = p_world_id
|
|
||||||
room_id = p_room_id
|
|
||||||
key = build_key(world_id, room_id, coord)
|
|
||||||
bounds = compute_bounds(coord)
|
|
||||||
|
|
||||||
|
|
||||||
## Build the canonical chunk key from its components.
|
|
||||||
static func build_key(p_world_id: String, p_room_id: String, p_coord: Vector3i) -> String:
|
|
||||||
return "%s:%s:%d:%d:%d" % [p_world_id, p_room_id, p_coord.x, p_coord.y, p_coord.z]
|
|
||||||
|
|
||||||
|
|
||||||
## Compute the world-space bounding box for a chunk coordinate.
|
|
||||||
static func compute_bounds(p_coord: Vector3i) -> AABB:
|
|
||||||
var min_pos := Vector3(
|
|
||||||
CHUNK_ORIGIN.x + p_coord.x * CHUNK_SIZE_X,
|
|
||||||
CHUNK_ORIGIN.y + p_coord.y * CHUNK_SIZE_Y,
|
|
||||||
CHUNK_ORIGIN.z + p_coord.z * CHUNK_SIZE_Z
|
|
||||||
)
|
|
||||||
return AABB(min_pos, Vector3(CHUNK_SIZE_X, CHUNK_SIZE_Y, CHUNK_SIZE_Z))
|
|
||||||
|
|
||||||
|
|
||||||
## Compute the chunk coordinate that contains a world-space position.
|
|
||||||
static func coord_for_position(p_pos: Vector3) -> Vector3i:
|
|
||||||
return Vector3i(
|
|
||||||
int(floor((p_pos.x - CHUNK_ORIGIN.x) / CHUNK_SIZE_X)),
|
|
||||||
int(floor((p_pos.y - CHUNK_ORIGIN.y) / CHUNK_SIZE_Y)),
|
|
||||||
int(floor((p_pos.z - CHUNK_ORIGIN.z) / CHUNK_SIZE_Z))
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
## Add a static object to this chunk.
|
|
||||||
func add_object(p_object: Node3D) -> void:
|
|
||||||
objects.append(p_object)
|
|
||||||
add_child(p_object)
|
|
||||||
|
|
||||||
|
|
||||||
## Add a dynamic object template to this chunk.
|
|
||||||
func add_dynamic_template(p_template: Node3D) -> void:
|
|
||||||
dynamic_templates.append(p_template)
|
|
||||||
add_child(p_template)
|
|
||||||
|
|
||||||
|
|
||||||
## Remove all objects from this chunk.
|
|
||||||
func clear_objects() -> void:
|
|
||||||
for obj in objects:
|
|
||||||
if is_instance_valid(obj):
|
|
||||||
obj.queue_free()
|
|
||||||
objects.clear()
|
|
||||||
dynamic_templates.clear()
|
|
||||||
|
|
||||||
|
|
||||||
## Mark this chunk as dirty (modified but not yet persisted).
|
|
||||||
func mark_dirty() -> void:
|
|
||||||
dirty = true
|
|
||||||
revision += 1
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://dc6j7kqjitc6g
|
|
||||||
@@ -1,667 +0,0 @@
|
|||||||
class_name ChunkDataDecoder
|
|
||||||
extends RefCounted
|
|
||||||
## Decodes chunk binary payloads (and JSON) into logical chunk data.
|
|
||||||
##
|
|
||||||
## Implements the binary format spec from docs/architecture/world.md §3.6.
|
|
||||||
## Both the Godot client and Python backend use this class to ensure
|
|
||||||
## identical encoding/decoding behavior.
|
|
||||||
##
|
|
||||||
## ## Binary Format Overview
|
|
||||||
##
|
|
||||||
## ```
|
|
||||||
## Header (48 bytes):
|
|
||||||
## [0:4] magic "AGPC"
|
|
||||||
## [4:6] version (uint16 LE)
|
|
||||||
## [6:8] header_len (uint16 LE)
|
|
||||||
## [8:12] flags (uint32 LE)
|
|
||||||
## [12:16] payload_len (uint32 LE)
|
|
||||||
## [16:48] checksum (SHA-256 hex, 32 bytes)
|
|
||||||
##
|
|
||||||
## Payload Body (sections):
|
|
||||||
## [section_id:1][section_len:4][data:section_len]
|
|
||||||
## ```
|
|
||||||
|
|
||||||
|
|
||||||
## Content flags parsed from a chunk.
|
|
||||||
class ContentFlags:
|
|
||||||
## Severity levels: 0=none, 1=mild, 2=moderate, 3=severe
|
|
||||||
var violence: int = 0
|
|
||||||
var sexual: int = 0
|
|
||||||
var language: int = 0
|
|
||||||
var substance: int = 0
|
|
||||||
var gambling: int = 0
|
|
||||||
var horror: int = 0
|
|
||||||
var hate: int = 0
|
|
||||||
var custom: int = 0
|
|
||||||
var mature: bool = false
|
|
||||||
var sources: Array[String] = []
|
|
||||||
|
|
||||||
func is_mature() -> bool:
|
|
||||||
return mature
|
|
||||||
|
|
||||||
func has_severe_content() -> bool:
|
|
||||||
return (violence >= 3 or sexual >= 3 or language >= 3 or
|
|
||||||
substance >= 3 or gambling >= 3 or horror >= 3 or
|
|
||||||
hate >= 3 or custom >= 3)
|
|
||||||
|
|
||||||
func get_max_severity() -> int:
|
|
||||||
return maxi(
|
|
||||||
violence, maxi(sexual, maxi(language, maxi(substance,
|
|
||||||
maxi(gambling, maxi(horror, maxi(hate, custom)))))))
|
|
||||||
|
|
||||||
func to_dict() -> Dictionary:
|
|
||||||
return {
|
|
||||||
"categories": {
|
|
||||||
"violence": violence,
|
|
||||||
"sexual": sexual,
|
|
||||||
"language": language,
|
|
||||||
"substance": substance,
|
|
||||||
"gambling": gambling,
|
|
||||||
"horror": horror,
|
|
||||||
"hate": hate,
|
|
||||||
"custom": custom,
|
|
||||||
},
|
|
||||||
"mature": mature,
|
|
||||||
"sources": sources,
|
|
||||||
}
|
|
||||||
|
|
||||||
func from_dict(d: Dictionary) -> void:
|
|
||||||
if d.has("categories"):
|
|
||||||
violence = d["categories"].get("violence", 0)
|
|
||||||
sexual = d["categories"].get("sexual", 0)
|
|
||||||
language = d["categories"].get("language", 0)
|
|
||||||
substance = d["categories"].get("substance", 0)
|
|
||||||
gambling = d["categories"].get("gambling", 0)
|
|
||||||
horror = d["categories"].get("horror", 0)
|
|
||||||
hate = d["categories"].get("hate", 0)
|
|
||||||
custom = d["categories"].get("custom", 0)
|
|
||||||
mature = d.get("mature", false)
|
|
||||||
sources = d.get("sources", [])
|
|
||||||
|
|
||||||
|
|
||||||
## A tile layer definition (palette + dense tile indices).
|
|
||||||
class TileLayerData:
|
|
||||||
var name: String = ""
|
|
||||||
var layer_id: int = 0
|
|
||||||
var width: int = 0
|
|
||||||
var height: int = 0
|
|
||||||
var depth: int = 1
|
|
||||||
var palette: Array[TileDef] = []
|
|
||||||
var tiles: PackedInt32Array = PackedInt32Array()
|
|
||||||
|
|
||||||
func tile_count() -> int:
|
|
||||||
return width * height * depth
|
|
||||||
|
|
||||||
func get_tile(x: int, y: int, z: int = 0) -> int:
|
|
||||||
if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
|
|
||||||
return 0 # Out of bounds returns empty tile
|
|
||||||
var idx := (z * height + y) * width + x
|
|
||||||
if idx < tiles.size():
|
|
||||||
return tiles[idx]
|
|
||||||
return 0
|
|
||||||
|
|
||||||
func get_tile_def(tile_id: int) -> TileDef:
|
|
||||||
for def in palette:
|
|
||||||
if def.id == tile_id:
|
|
||||||
return def
|
|
||||||
return null
|
|
||||||
|
|
||||||
|
|
||||||
## A world object parsed from chunk data.
|
|
||||||
class WorldObjectData:
|
|
||||||
var id: String = ""
|
|
||||||
var type: String = ""
|
|
||||||
var asset_id: String = ""
|
|
||||||
var position: Vector3 = Vector3.ZERO
|
|
||||||
var rotation: Vector4 = Vector4(0, 0, 0, 1)
|
|
||||||
var scale: Vector3 = Vector3.ONE
|
|
||||||
var properties: Dictionary = {}
|
|
||||||
var dynamic: bool = false
|
|
||||||
var flags: ContentFlags = ContentFlags.new()
|
|
||||||
|
|
||||||
|
|
||||||
## The complete decoded chunk payload.
|
|
||||||
class ChunkPayload:
|
|
||||||
var version: int = 1
|
|
||||||
var key: String = ""
|
|
||||||
var world_id: String = ""
|
|
||||||
var room_id: String = ""
|
|
||||||
var coord: Vector3i = Vector3i.ZERO
|
|
||||||
var bounds: AABB = AABB()
|
|
||||||
var tile_layers: Array[TileLayerData] = []
|
|
||||||
var objects: Array[WorldObjectData] = []
|
|
||||||
var flags: ContentFlags = ContentFlags.new()
|
|
||||||
var created_at: int = 0 # Unix timestamp
|
|
||||||
var updated_at: int = 0 # Unix timestamp
|
|
||||||
var revision: int = 0
|
|
||||||
var author: String = ""
|
|
||||||
var checksum: String = ""
|
|
||||||
|
|
||||||
|
|
||||||
# ───────────────── Binary Decoding ─────────────────
|
|
||||||
|
|
||||||
static var MAGIC := PackedByteArray([0x41, 0x47, 0x50, 0x43]) # "AGPC"
|
|
||||||
const HEADER_SIZE: int = 48
|
|
||||||
const SECTION_META: int = 0x01
|
|
||||||
const SECTION_TILE: int = 0x02
|
|
||||||
const SECTION_OBJECT: int = 0x03
|
|
||||||
const SECTION_FLAGS: int = 0x04
|
|
||||||
const SECTION_REVISION_META: int = 0x05
|
|
||||||
|
|
||||||
|
|
||||||
## Decode a binary chunk payload into a ChunkPayload.
|
|
||||||
## Returns null if the data is invalid or version is unsupported.
|
|
||||||
static func decode_binary(data: PackedByteArray) -> ChunkPayload:
|
|
||||||
if data.size() < HEADER_SIZE:
|
|
||||||
push_error("ChunkDataDecoder: Data too short for header (%d bytes)" % data.size())
|
|
||||||
return null
|
|
||||||
|
|
||||||
# Verify magic
|
|
||||||
var magic := PackedByteArray(data.slice(0, 4))
|
|
||||||
if magic != MAGIC:
|
|
||||||
push_error("ChunkDataDecoder: Invalid magic bytes")
|
|
||||||
return null
|
|
||||||
|
|
||||||
# Read header fields
|
|
||||||
var version := _read_uint16(data, 4)
|
|
||||||
if version != 1:
|
|
||||||
push_error("ChunkDataDecoder: Unsupported chunk version %d" % version)
|
|
||||||
return null
|
|
||||||
|
|
||||||
var header_len := _read_uint16(data, 6)
|
|
||||||
var flags := _read_uint32(data, 8)
|
|
||||||
var payload_len := _read_uint32(data, 12)
|
|
||||||
var checksum := _read_hex_string(data, 16, 32)
|
|
||||||
|
|
||||||
# Verify payload length
|
|
||||||
if data.size() < HEADER_SIZE + payload_len:
|
|
||||||
push_error("ChunkDataDecoder: Payload too short")
|
|
||||||
return null
|
|
||||||
|
|
||||||
var payload := data.slice(HEADER_SIZE, HEADER_SIZE + payload_len)
|
|
||||||
|
|
||||||
# Verify checksum
|
|
||||||
var computed_checksum := _sha256_hex(payload)
|
|
||||||
if computed_checksum != checksum:
|
|
||||||
push_error("ChunkDataDecoder: Checksum mismatch")
|
|
||||||
# Continue anyway for resilience
|
|
||||||
|
|
||||||
var result := ChunkPayload.new()
|
|
||||||
result.version = version
|
|
||||||
result.checksum = checksum
|
|
||||||
|
|
||||||
# Parse sections
|
|
||||||
var offset := 0
|
|
||||||
while offset < payload.size():
|
|
||||||
if offset + 5 > payload.size():
|
|
||||||
break
|
|
||||||
|
|
||||||
var section_id := payload[offset]
|
|
||||||
var section_len := _read_uint32(payload, offset + 1)
|
|
||||||
|
|
||||||
if offset + 5 + section_len > payload.size():
|
|
||||||
break
|
|
||||||
|
|
||||||
var section_data := payload.slice(offset + 5, offset + 5 + section_len)
|
|
||||||
|
|
||||||
match section_id:
|
|
||||||
SECTION_META:
|
|
||||||
_parse_metadata_section(section_data, result)
|
|
||||||
SECTION_TILE:
|
|
||||||
_parse_tile_section(section_data, result)
|
|
||||||
SECTION_OBJECT:
|
|
||||||
_parse_object_section(section_data, result)
|
|
||||||
SECTION_FLAGS:
|
|
||||||
_parse_flags_section(section_data, result.flags)
|
|
||||||
SECTION_REVISION_META:
|
|
||||||
_parse_revision_meta_section(section_data, result)
|
|
||||||
|
|
||||||
offset += 5 + section_len
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
|
|
||||||
## Encode a ChunkPayload into binary format.
|
|
||||||
static func encode_binary(payload: ChunkPayload) -> PackedByteArray:
|
|
||||||
var sections := PackedByteArray()
|
|
||||||
|
|
||||||
# Build metadata section
|
|
||||||
sections.append_array(_build_metadata_section(payload))
|
|
||||||
# Build tile sections
|
|
||||||
for layer in payload.tile_layers:
|
|
||||||
sections.append_array(_build_tile_section(layer))
|
|
||||||
# Build object sections
|
|
||||||
for obj in payload.objects:
|
|
||||||
sections.append_array(_build_object_section(obj))
|
|
||||||
# Build flags section
|
|
||||||
sections.append_array(_build_flags_section(payload.flags))
|
|
||||||
# Build revision meta section
|
|
||||||
sections.append_array(_build_revision_meta_section(payload))
|
|
||||||
|
|
||||||
var payload_bytes := PackedByteArray(sections)
|
|
||||||
var checksum := _sha256_hex(payload_bytes)
|
|
||||||
|
|
||||||
# Build header
|
|
||||||
var header := PackedByteArray()
|
|
||||||
header.append_array(MAGIC)
|
|
||||||
header.append_array(_write_uint16(1)) # version
|
|
||||||
header.append_array(_write_uint16(0)) # header_len (after this field)
|
|
||||||
header.append_array(_write_uint32(0)) # flags
|
|
||||||
header.append_array(_write_uint32(payload_bytes.size()))
|
|
||||||
header.append_array(_hex_to_bytes(checksum))
|
|
||||||
|
|
||||||
return header + payload_bytes
|
|
||||||
|
|
||||||
|
|
||||||
# ───────────────── Section Parsers ─────────────────
|
|
||||||
|
|
||||||
static func _parse_metadata_section(data: PackedByteArray, result: ChunkPayload) -> void:
|
|
||||||
var offset := 0
|
|
||||||
|
|
||||||
# world_id (length-prefixed string)
|
|
||||||
var world_id_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
result.world_id = data.slice(offset, offset + world_id_len).get_string_from_utf8()
|
|
||||||
offset += world_id_len
|
|
||||||
|
|
||||||
# room_id (length-prefixed string)
|
|
||||||
var room_id_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
result.room_id = data.slice(offset, offset + room_id_len).get_string_from_utf8()
|
|
||||||
offset += room_id_len
|
|
||||||
|
|
||||||
# coord (3 × int32)
|
|
||||||
result.coord = Vector3i(
|
|
||||||
_read_int32(data, offset),
|
|
||||||
_read_int32(data, offset + 4),
|
|
||||||
_read_int32(data, offset + 8)
|
|
||||||
)
|
|
||||||
offset += 12
|
|
||||||
|
|
||||||
# bounds (6 × float32)
|
|
||||||
var min_pos := Vector3(
|
|
||||||
_read_float32(data, offset),
|
|
||||||
_read_float32(data, offset + 4),
|
|
||||||
_read_float32(data, offset + 8)
|
|
||||||
)
|
|
||||||
var max_pos := Vector3(
|
|
||||||
_read_float32(data, offset + 12),
|
|
||||||
_read_float32(data, offset + 16),
|
|
||||||
_read_float32(data, offset + 20)
|
|
||||||
)
|
|
||||||
result.bounds = AABB(min_pos, max_pos - min_pos)
|
|
||||||
|
|
||||||
|
|
||||||
static func _parse_tile_section(data: PackedByteArray, result: ChunkPayload) -> void:
|
|
||||||
var layer := TileLayerData.new()
|
|
||||||
var offset := 0
|
|
||||||
|
|
||||||
# name (length-prefixed string)
|
|
||||||
var name_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
layer.name = data.slice(offset, offset + name_len).get_string_from_utf8()
|
|
||||||
offset += name_len
|
|
||||||
|
|
||||||
# layer_id (uint16)
|
|
||||||
layer.layer_id = _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
|
|
||||||
# dimensions (3 × uint16)
|
|
||||||
layer.width = _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
layer.height = _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
layer.depth = _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
|
|
||||||
# palette
|
|
||||||
var palette_count := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
for _i in range(palette_count):
|
|
||||||
var tile_def := TileDef.new()
|
|
||||||
tile_def.id = _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
|
|
||||||
var asset_id_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
tile_def.asset_id = data.slice(offset, offset + asset_id_len).get_string_from_utf8()
|
|
||||||
offset += asset_id_len
|
|
||||||
|
|
||||||
tile_def.solid = data[offset] != 0
|
|
||||||
offset += 1
|
|
||||||
|
|
||||||
tile_def.flags = _read_uint32(data, offset)
|
|
||||||
offset += 4
|
|
||||||
|
|
||||||
tile_def.variants = data[offset]
|
|
||||||
offset += 1
|
|
||||||
|
|
||||||
layer.palette.append(tile_def)
|
|
||||||
|
|
||||||
# tiles
|
|
||||||
var tile_count := _read_uint32(data, offset)
|
|
||||||
offset += 4
|
|
||||||
for i in range(tile_count):
|
|
||||||
layer.tiles.append(_read_uint16(data, offset))
|
|
||||||
offset += 2
|
|
||||||
|
|
||||||
result.tile_layers.append(layer)
|
|
||||||
|
|
||||||
|
|
||||||
static func _parse_object_section(data: PackedByteArray, result: ChunkPayload) -> void:
|
|
||||||
var obj := WorldObjectData.new()
|
|
||||||
var offset := 0
|
|
||||||
|
|
||||||
# id (length-prefixed string)
|
|
||||||
var id_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
obj.id = data.slice(offset, offset + id_len).get_string_from_utf8()
|
|
||||||
offset += id_len
|
|
||||||
|
|
||||||
# type (length-prefixed string)
|
|
||||||
var type_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
obj.type = data.slice(offset, offset + type_len).get_string_from_utf8()
|
|
||||||
offset += type_len
|
|
||||||
|
|
||||||
# asset_id (length-prefixed string)
|
|
||||||
var asset_id_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
obj.asset_id = data.slice(offset, offset + asset_id_len).get_string_from_utf8()
|
|
||||||
offset += asset_id_len
|
|
||||||
|
|
||||||
# position (3 × float32)
|
|
||||||
obj.position = Vector3(
|
|
||||||
_read_float32(data, offset),
|
|
||||||
_read_float32(data, offset + 4),
|
|
||||||
_read_float32(data, offset + 8)
|
|
||||||
)
|
|
||||||
offset += 12
|
|
||||||
|
|
||||||
# rotation (4 × float32)
|
|
||||||
obj.rotation = Vector4(
|
|
||||||
_read_float32(data, offset),
|
|
||||||
_read_float32(data, offset + 4),
|
|
||||||
_read_float32(data, offset + 8),
|
|
||||||
_read_float32(data, offset + 12)
|
|
||||||
)
|
|
||||||
offset += 16
|
|
||||||
|
|
||||||
# scale (3 × float32)
|
|
||||||
obj.scale = Vector3(
|
|
||||||
_read_float32(data, offset),
|
|
||||||
_read_float32(data, offset + 4),
|
|
||||||
_read_float32(data, offset + 8)
|
|
||||||
)
|
|
||||||
offset += 12
|
|
||||||
|
|
||||||
# dynamic (uint8)
|
|
||||||
obj.dynamic = data[offset] != 0
|
|
||||||
offset += 1
|
|
||||||
|
|
||||||
# properties (length-prefixed JSON string)
|
|
||||||
var props_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
var props_str := data.slice(offset, offset + props_len).get_string_from_utf8()
|
|
||||||
offset += props_len
|
|
||||||
obj.properties = JSON.parse_string(props_str) or {}
|
|
||||||
|
|
||||||
# flags (ContentFlags)
|
|
||||||
obj.flags.violence = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.sexual = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.language = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.substance = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.gambling = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.horror = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.hate = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.custom = data[offset]
|
|
||||||
offset += 1
|
|
||||||
obj.flags.mature = data[offset] != 0
|
|
||||||
offset += 1
|
|
||||||
|
|
||||||
var source_count := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
for _i in range(source_count):
|
|
||||||
var src_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
obj.flags.sources.append(data.slice(offset, offset + src_len).get_string_from_utf8())
|
|
||||||
offset += src_len
|
|
||||||
|
|
||||||
result.objects.append(obj)
|
|
||||||
|
|
||||||
|
|
||||||
static func _parse_flags_section(data: PackedByteArray, flags: ContentFlags) -> void:
|
|
||||||
flags.violence = data[0]
|
|
||||||
flags.sexual = data[1]
|
|
||||||
flags.language = data[2]
|
|
||||||
flags.substance = data[3]
|
|
||||||
flags.gambling = data[4]
|
|
||||||
flags.horror = data[5]
|
|
||||||
flags.hate = data[6]
|
|
||||||
flags.custom = data[7]
|
|
||||||
flags.mature = data[8] != 0
|
|
||||||
|
|
||||||
var offset := 9
|
|
||||||
var source_count := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
for _i in range(source_count):
|
|
||||||
var src_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
flags.sources.append(data.slice(offset, offset + src_len).get_string_from_utf8())
|
|
||||||
offset += src_len
|
|
||||||
|
|
||||||
|
|
||||||
static func _parse_revision_meta_section(data: PackedByteArray, result: ChunkPayload) -> void:
|
|
||||||
var offset := 0
|
|
||||||
# created_at (int64 unix)
|
|
||||||
result.created_at = _read_int64(data, offset)
|
|
||||||
offset += 8
|
|
||||||
# updated_at (int64 unix)
|
|
||||||
result.updated_at = _read_int64(data, offset)
|
|
||||||
offset += 8
|
|
||||||
# revision (uint32)
|
|
||||||
result.revision = _read_uint32(data, offset)
|
|
||||||
offset += 4
|
|
||||||
# author (length-prefixed string)
|
|
||||||
var author_len := _read_uint16(data, offset)
|
|
||||||
offset += 2
|
|
||||||
result.author = data.slice(offset, offset + author_len).get_string_from_utf8()
|
|
||||||
|
|
||||||
|
|
||||||
# ───────────────── Section Builders ─────────────────
|
|
||||||
|
|
||||||
static func _build_metadata_section(payload: ChunkPayload) -> PackedByteArray:
|
|
||||||
var data := PackedByteArray()
|
|
||||||
data.append_array(_write_string(payload.world_id))
|
|
||||||
data.append_array(_write_string(payload.room_id))
|
|
||||||
data.append_array(_write_int32(payload.coord.x))
|
|
||||||
data.append_array(_write_int32(payload.coord.y))
|
|
||||||
data.append_array(_write_int32(payload.coord.z))
|
|
||||||
data.append_array(_write_float32(payload.bounds.position.x))
|
|
||||||
data.append_array(_write_float32(payload.bounds.position.y))
|
|
||||||
data.append_array(_write_float32(payload.bounds.position.z))
|
|
||||||
data.append_array(_write_float32(payload.bounds.size.x))
|
|
||||||
data.append_array(_write_float32(payload.bounds.size.y))
|
|
||||||
data.append_array(_write_float32(payload.bounds.size.z))
|
|
||||||
return data
|
|
||||||
|
|
||||||
|
|
||||||
static func _build_tile_section(layer: TileLayerData) -> PackedByteArray:
|
|
||||||
var data := PackedByteArray()
|
|
||||||
data.append_array(_write_string(layer.name))
|
|
||||||
data.append_array(_write_uint16(layer.layer_id))
|
|
||||||
data.append_array(_write_uint16(layer.width))
|
|
||||||
data.append_array(_write_uint16(layer.height))
|
|
||||||
data.append_array(_write_uint16(layer.depth))
|
|
||||||
data.append_array(_write_uint16(layer.palette.size()))
|
|
||||||
|
|
||||||
for tile_def in layer.palette:
|
|
||||||
data.append_array(_write_uint16(tile_def.id))
|
|
||||||
data.append_array(_write_string(tile_def.asset_id))
|
|
||||||
data.append(tile_def.solid as int)
|
|
||||||
data.append_array(_write_uint32(tile_def.flags))
|
|
||||||
data.append(tile_def.variants)
|
|
||||||
|
|
||||||
data.append_array(_write_uint32(layer.tiles.size()))
|
|
||||||
for tile_id in layer.tiles:
|
|
||||||
data.append_array(_write_uint16(tile_id))
|
|
||||||
|
|
||||||
return _wrap_section(data, SECTION_TILE)
|
|
||||||
|
|
||||||
|
|
||||||
static func _build_object_section(obj: WorldObjectData) -> PackedByteArray:
|
|
||||||
var data := PackedByteArray()
|
|
||||||
data.append_array(_write_string(obj.id))
|
|
||||||
data.append_array(_write_string(obj.type))
|
|
||||||
data.append_array(_write_string(obj.asset_id))
|
|
||||||
data.append_array(_write_float32(obj.position.x))
|
|
||||||
data.append_array(_write_float32(obj.position.y))
|
|
||||||
data.append_array(_write_float32(obj.position.z))
|
|
||||||
data.append_array(_write_float32(obj.rotation.x))
|
|
||||||
data.append_array(_write_float32(obj.rotation.y))
|
|
||||||
data.append_array(_write_float32(obj.rotation.z))
|
|
||||||
data.append_array(_write_float32(obj.rotation.w))
|
|
||||||
data.append_array(_write_float32(obj.scale.x))
|
|
||||||
data.append_array(_write_float32(obj.scale.y))
|
|
||||||
data.append_array(_write_float32(obj.scale.z))
|
|
||||||
data.append(obj.dynamic as int)
|
|
||||||
|
|
||||||
var props_json := JSON.stringify(obj.properties, " ")
|
|
||||||
data.append_array(_write_string(props_json))
|
|
||||||
|
|
||||||
data.append(obj.flags.violence)
|
|
||||||
data.append(obj.flags.sexual)
|
|
||||||
data.append(obj.flags.language)
|
|
||||||
data.append(obj.flags.substance)
|
|
||||||
data.append(obj.flags.gambling)
|
|
||||||
data.append(obj.flags.horror)
|
|
||||||
data.append(obj.flags.hate)
|
|
||||||
data.append(obj.flags.custom)
|
|
||||||
data.append(obj.flags.mature as int)
|
|
||||||
data.append_array(_write_uint16(obj.flags.sources.size()))
|
|
||||||
for src in obj.flags.sources:
|
|
||||||
data.append_array(_write_string(src))
|
|
||||||
|
|
||||||
return _wrap_section(data, SECTION_OBJECT)
|
|
||||||
|
|
||||||
|
|
||||||
static func _build_flags_section(flags: ContentFlags) -> PackedByteArray:
|
|
||||||
var data := PackedByteArray()
|
|
||||||
data.append(flags.violence)
|
|
||||||
data.append(flags.sexual)
|
|
||||||
data.append(flags.language)
|
|
||||||
data.append(flags.substance)
|
|
||||||
data.append(flags.gambling)
|
|
||||||
data.append(flags.horror)
|
|
||||||
data.append(flags.hate)
|
|
||||||
data.append(flags.custom)
|
|
||||||
data.append(flags.mature as int)
|
|
||||||
data.append_array(_write_uint16(flags.sources.size()))
|
|
||||||
for src in flags.sources:
|
|
||||||
data.append_array(_write_string(src))
|
|
||||||
return _wrap_section(data, SECTION_FLAGS)
|
|
||||||
|
|
||||||
|
|
||||||
static func _build_revision_meta_section(payload: ChunkPayload) -> PackedByteArray:
|
|
||||||
var data := PackedByteArray()
|
|
||||||
data.append_array(_write_int64(payload.created_at))
|
|
||||||
data.append_array(_write_int64(payload.updated_at))
|
|
||||||
data.append_array(_write_uint32(payload.revision))
|
|
||||||
data.append_array(_write_string(payload.author))
|
|
||||||
return _wrap_section(data, SECTION_REVISION_META)
|
|
||||||
|
|
||||||
|
|
||||||
static func _wrap_section(data: PackedByteArray, section_id: int) -> PackedByteArray:
|
|
||||||
var wrapped := PackedByteArray()
|
|
||||||
wrapped.append(section_id)
|
|
||||||
wrapped.append_array(_write_uint32(data.size()))
|
|
||||||
wrapped.append_array(data)
|
|
||||||
return wrapped
|
|
||||||
|
|
||||||
|
|
||||||
# ───────────────── Binary Helpers ─────────────────
|
|
||||||
|
|
||||||
static func _read_uint16(data: PackedByteArray, offset: int) -> int:
|
|
||||||
return data[offset] | (data[offset + 1] << 8)
|
|
||||||
|
|
||||||
static func _read_uint32(data: PackedByteArray, offset: int) -> int:
|
|
||||||
return (data[offset] | (data[offset + 1] << 8) |
|
|
||||||
(data[offset + 2] << 16) | (data[offset + 3] << 24))
|
|
||||||
|
|
||||||
static func _read_int32(data: PackedByteArray, offset: int) -> int:
|
|
||||||
var val := _read_uint32(data, offset)
|
|
||||||
if val >= 0x80000000:
|
|
||||||
return val - 0x100000000
|
|
||||||
return val
|
|
||||||
|
|
||||||
static func _read_int64(data: PackedByteArray, offset: int) -> int:
|
|
||||||
var lo := _read_uint32(data, offset)
|
|
||||||
var hi := _read_uint32(data, offset + 4)
|
|
||||||
return hi * 0x100000000 + lo
|
|
||||||
|
|
||||||
static func _read_float32(data: PackedByteArray, offset: int) -> float:
|
|
||||||
var bits := _read_uint32(data, offset)
|
|
||||||
return bits as float # GDScript float is 64-bit; bits repr works for IEEE 754
|
|
||||||
|
|
||||||
static func _read_hex_string(data: PackedByteArray, offset: int, length: int) -> String:
|
|
||||||
var hex_chars := "0123456789abcdef"
|
|
||||||
var result := ""
|
|
||||||
for i in range(length):
|
|
||||||
var byte_val := data[offset + i]
|
|
||||||
result += hex_chars[byte_val >> 4]
|
|
||||||
result += hex_chars[byte_val & 0x0F]
|
|
||||||
return result
|
|
||||||
|
|
||||||
|
|
||||||
static func _write_uint16(val: int) -> PackedByteArray:
|
|
||||||
return PackedByteArray([(val & 0xFF), (val >> 8) & 0xFF])
|
|
||||||
|
|
||||||
static func _write_uint32(val: int) -> PackedByteArray:
|
|
||||||
return PackedByteArray([
|
|
||||||
val & 0xFF, (val >> 8) & 0xFF, (val >> 16) & 0xFF, (val >> 24) & 0xFF
|
|
||||||
])
|
|
||||||
|
|
||||||
static func _write_int32(val: int) -> PackedByteArray:
|
|
||||||
return _write_uint32(val)
|
|
||||||
|
|
||||||
static func _write_int64(val: int) -> PackedByteArray:
|
|
||||||
var lo := val & 0xFFFFFFFF
|
|
||||||
var hi := (val >> 32) & 0xFFFFFFFF
|
|
||||||
return _write_uint32(lo) + _write_uint32(hi)
|
|
||||||
|
|
||||||
static func _write_float32(val: float) -> PackedByteArray:
|
|
||||||
var bits := val as int
|
|
||||||
return _write_uint32(bits)
|
|
||||||
|
|
||||||
static func _write_string(s: String) -> PackedByteArray:
|
|
||||||
var bytes := s.to_utf8_buffer()
|
|
||||||
return _write_uint16(bytes.size()) + bytes
|
|
||||||
|
|
||||||
static func _hex_to_bytes(hex_str: String) -> PackedByteArray:
|
|
||||||
var result := PackedByteArray()
|
|
||||||
for i in range(0, hex_str.length(), 2):
|
|
||||||
var byte_val := ("0x" + hex_str.substr(i, 2)).hex_to_int()
|
|
||||||
result.append(byte_val)
|
|
||||||
return result
|
|
||||||
|
|
||||||
|
|
||||||
# ───────────────── SHA-256 ─────────────────
|
|
||||||
|
|
||||||
static func _sha256_hex(data: PackedByteArray) -> String:
|
|
||||||
var ctx := HashingContext.new()
|
|
||||||
ctx.start(HashingContext.HASH_SHA256)
|
|
||||||
ctx.update(data)
|
|
||||||
var hash := ctx.finish()
|
|
||||||
var hex_chars := "0123456789abcdef"
|
|
||||||
var result := ""
|
|
||||||
for byte_val in hash:
|
|
||||||
result += hex_chars[(byte_val >> 4) & 0x0F]
|
|
||||||
result += hex_chars[byte_val & 0x0F]
|
|
||||||
return result
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://bv445xrd6f5tk
|
|
||||||
@@ -1,170 +0,0 @@
|
|||||||
class_name ChunkScene
|
|
||||||
extends Node3D
|
|
||||||
## A visual representation of a single loaded world chunk.
|
|
||||||
##
|
|
||||||
## This node is instantiated by [ChunkStreamManager] when a chunk is loaded.
|
|
||||||
## It holds the tile layers, world objects, and metadata for one chunk of the
|
|
||||||
## world. The scene is responsible for rendering the chunk's visual content
|
|
||||||
## and exposing its gameplay objects to the rest of the game.
|
|
||||||
##
|
|
||||||
## ## Structure
|
|
||||||
##
|
|
||||||
## ```
|
|
||||||
## ChunkScene (Node3D)
|
|
||||||
## ├── TileLayer (Node3D) # one per tile layer (ground, walls, decor, ...)
|
|
||||||
## ├── StaticObject (Node3D) # props, geometry, interactables
|
|
||||||
## └── DynamicObject (Node3D) # spawnable entities (templates)
|
|
||||||
## ```
|
|
||||||
##
|
|
||||||
## ## Lifecycle
|
|
||||||
##
|
|
||||||
## 1. [ChunkStreamManager] requests chunk data from the server.
|
|
||||||
## 2. Server responds with binary payload.
|
|
||||||
## 3. [ChunkStreamManager] decodes the payload and creates a [ChunkScene].
|
|
||||||
## 4. [ChunkScene] populates itself with tile layers and objects.
|
|
||||||
## 5. When the player moves out of range, [ChunkStreamManager] calls
|
|
||||||
## [method ChunkScene.queue_free] to unload it.
|
|
||||||
|
|
||||||
## The chunk coordinate this scene represents.
|
|
||||||
var coord: Vector3i = Vector3i.ZERO
|
|
||||||
|
|
||||||
## The canonical chunk key.
|
|
||||||
var key: String = ""
|
|
||||||
|
|
||||||
## World-space bounding box of this chunk.
|
|
||||||
var bounds: AABB = AABB()
|
|
||||||
|
|
||||||
## Format version of the chunk data.
|
|
||||||
var format_version: int = 1
|
|
||||||
|
|
||||||
## Revision counter from the server.
|
|
||||||
var revision: int = 0
|
|
||||||
|
|
||||||
## List of tile layers in this chunk.
|
|
||||||
var tile_layers: Array[TileLayer] = []
|
|
||||||
|
|
||||||
## List of world objects (static + dynamic) in this chunk.
|
|
||||||
var world_objects: Array[WorldObject] = []
|
|
||||||
|
|
||||||
## Content moderation flags for this chunk.
|
|
||||||
var content_flags: ChunkDataDecoder.ContentFlags = ChunkDataDecoder.ContentFlags.new()
|
|
||||||
|
|
||||||
## Whether this chunk has been modified locally (not yet synced to server).
|
|
||||||
var is_dirty: bool = false
|
|
||||||
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# Position this chunk scene at its world-space origin
|
|
||||||
global_position = bounds.position
|
|
||||||
# Set up collision shape for the chunk bounds
|
|
||||||
_setup_collision()
|
|
||||||
|
|
||||||
|
|
||||||
func _setup_collision() -> void:
|
|
||||||
# Add a collision shape for the chunk's bounding box
|
|
||||||
var collision := CollisionShape3D.new()
|
|
||||||
var shape := BoxShape3D.new()
|
|
||||||
shape.size = bounds.size
|
|
||||||
collision.shape = shape
|
|
||||||
collision.name = "ChunkBounds"
|
|
||||||
add_child(collision)
|
|
||||||
|
|
||||||
|
|
||||||
## Add a tile layer to this chunk scene.
|
|
||||||
func add_tile_layer(layer: TileLayer) -> void:
|
|
||||||
tile_layers.append(layer)
|
|
||||||
var layer_node := TileLayerNode.new()
|
|
||||||
layer_node.tile_layer = layer
|
|
||||||
layer_node.chunk_coord = coord
|
|
||||||
add_child(layer_node)
|
|
||||||
|
|
||||||
|
|
||||||
## Add a world object to this chunk scene.
|
|
||||||
func add_object(obj: WorldObject) -> void:
|
|
||||||
world_objects.append(obj)
|
|
||||||
if obj.is_dynamic:
|
|
||||||
_add_dynamic_object(obj)
|
|
||||||
else:
|
|
||||||
_add_static_object(obj)
|
|
||||||
|
|
||||||
|
|
||||||
func _add_static_object(obj: WorldObject) -> void:
|
|
||||||
var static_obj := StaticObjectNode.new()
|
|
||||||
static_obj.world_object = obj
|
|
||||||
static_obj.position = obj.position
|
|
||||||
static_obj.quaternion = Quaternion(obj.rotation.x, obj.rotation.y, obj.rotation.z, obj.rotation.w)
|
|
||||||
static_obj.scale = obj.scale
|
|
||||||
static_obj.name = "static_%s" % obj.id
|
|
||||||
add_child(static_obj)
|
|
||||||
|
|
||||||
|
|
||||||
func _add_dynamic_object(obj: WorldObject) -> void:
|
|
||||||
var dynamic_obj := DynamicObjectNode.new()
|
|
||||||
dynamic_obj.world_object = obj
|
|
||||||
dynamic_obj.position = obj.position
|
|
||||||
dynamic_obj.quaternion = Quaternion(obj.rotation.x, obj.rotation.y, obj.rotation.z, obj.rotation.w)
|
|
||||||
dynamic_obj.scale = obj.scale
|
|
||||||
dynamic_obj.name = "dynamic_%s" % obj.id
|
|
||||||
add_child(dynamic_obj)
|
|
||||||
|
|
||||||
|
|
||||||
## Get a world object by its ID.
|
|
||||||
func get_object_by_id(object_id: String) -> WorldObject:
|
|
||||||
for obj in world_objects:
|
|
||||||
if obj.id == object_id:
|
|
||||||
return obj
|
|
||||||
return null
|
|
||||||
|
|
||||||
|
|
||||||
## Get all static objects in this chunk.
|
|
||||||
func get_static_objects() -> Array[WorldObject]:
|
|
||||||
var result: Array[WorldObject] = []
|
|
||||||
for obj in world_objects:
|
|
||||||
if not obj.is_dynamic:
|
|
||||||
result.append(obj)
|
|
||||||
return result
|
|
||||||
|
|
||||||
|
|
||||||
## Get all dynamic object templates in this chunk.
|
|
||||||
func get_dynamic_templates() -> Array[WorldObject]:
|
|
||||||
var result: Array[WorldObject] = []
|
|
||||||
for obj in world_objects:
|
|
||||||
if obj.is_dynamic:
|
|
||||||
result.append(obj)
|
|
||||||
return result
|
|
||||||
|
|
||||||
|
|
||||||
## Mark this chunk as dirty (locally modified).
|
|
||||||
func mark_dirty() -> void:
|
|
||||||
is_dirty = true
|
|
||||||
|
|
||||||
|
|
||||||
## Clear all objects and tile layers from this chunk.
|
|
||||||
func clear() -> void:
|
|
||||||
for child in get_children():
|
|
||||||
if child is TileLayerNode or child is StaticObjectNode or child is DynamicObjectNode:
|
|
||||||
child.queue_free()
|
|
||||||
tile_layers.clear()
|
|
||||||
world_objects.clear()
|
|
||||||
|
|
||||||
|
|
||||||
## Get the world-space position of a tile within this chunk.
|
|
||||||
func get_tile_world_position(tile_x: int, tile_y: int, tile_z: int = 0) -> Vector3:
|
|
||||||
return bounds.position + Vector3(
|
|
||||||
tile_x * 1.0, # Tile size is 1 world unit
|
|
||||||
tile_y * 1.0,
|
|
||||||
tile_z * 1.0
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
## Check if a world-space position is within this chunk's bounds.
|
|
||||||
func contains_position(pos: Vector3) -> bool:
|
|
||||||
return bounds.has_point(pos)
|
|
||||||
|
|
||||||
|
|
||||||
## Check if a chunk coordinate is adjacent to this chunk.
|
|
||||||
func is_adjacent(other_coord: Vector3i) -> bool:
|
|
||||||
var dx: int = abs(coord.x - other_coord.x)
|
|
||||||
var dy: int = abs(coord.y - other_coord.y)
|
|
||||||
var dz: int = abs(coord.z - other_coord.z)
|
|
||||||
return dx <= 1 and dy <= 1 and dz <= 1 and (dx + dy + dz) > 0
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://d4gh4h5iey6xb
|
|
||||||
@@ -1,358 +0,0 @@
|
|||||||
class_name ChunkStreamManager
|
|
||||||
extends Node
|
|
||||||
## Manages loading and unloading of world chunks based on player position.
|
|
||||||
##
|
|
||||||
## This is the central orchestrator for the chunk streaming system. It monitors
|
|
||||||
## the player's position, determines which chunks should be loaded, requests
|
|
||||||
## chunk data from the server, instantiates ChunkScene nodes, and unloads
|
|
||||||
## chunks that fall outside the streaming radius.
|
|
||||||
##
|
|
||||||
## ## Design
|
|
||||||
##
|
|
||||||
## - **Streaming radius** defines how many chunks around the player are kept
|
|
||||||
## loaded. Chunks beyond this radius are unloaded to save memory and CPU.
|
|
||||||
## - **Load priority** ensures chunks closer to the player are loaded first,
|
|
||||||
## preventing visual pop-in at the edge of the view.
|
|
||||||
## - **Server communication** uses the RPCs defined in docs/architecture/world.md
|
|
||||||
## (§5.3): `request_chunk`, `chunk_data`, `chunk_invalidated`.
|
|
||||||
##
|
|
||||||
## ## Usage
|
|
||||||
##
|
|
||||||
## Add this node to your scene tree and set the `player` reference:
|
|
||||||
## ```gdscript
|
|
||||||
## var stream_manager: ChunkStreamManager = $ChunkStreamManager
|
|
||||||
## stream_manager.player = $Player
|
|
||||||
## stream_manager.streaming_radius = 4 # chunks
|
|
||||||
## ```
|
|
||||||
|
|
||||||
## Number of chunks (radius) to keep loaded around the player.
|
|
||||||
## A radius of 2 means a 5x5 grid of chunks centered on the player.
|
|
||||||
## Higher values increase memory usage but reduce streaming pop-in.
|
|
||||||
@export var streaming_radius: int = 3
|
|
||||||
|
|
||||||
## Maximum number of chunks to load per frame. Prevents frame spikes during
|
|
||||||
## rapid movement or when entering a new area.
|
|
||||||
@export var max_loads_per_frame: int = 4
|
|
||||||
|
|
||||||
## Maximum number of chunks to unload per frame.
|
|
||||||
@export var max_unloads_per_frame: int = 4
|
|
||||||
|
|
||||||
## Distance (in chunks) from the streaming radius edge before a chunk is
|
|
||||||
## considered for unloading. Prevents rapid load/unload cycling.
|
|
||||||
@export var unload_margin: int = 1
|
|
||||||
|
|
||||||
## Emitted when a chunk finishes loading.
|
|
||||||
signal chunk_loaded(chunk_coord: Vector3i, chunk_scene: Node)
|
|
||||||
|
|
||||||
## Emitted when a chunk is unloaded.
|
|
||||||
signal chunk_unloaded(chunk_coord: Vector3i)
|
|
||||||
|
|
||||||
## Emitted when a chunk fails to load (e.g., server error).
|
|
||||||
signal chunk_load_failed(chunk_coord: Vector3i, error: String)
|
|
||||||
|
|
||||||
## Emitted when the player moves far enough to require a streaming update.
|
|
||||||
signal streaming_updated
|
|
||||||
|
|
||||||
## Reference to the player node. Must be set before the manager starts.
|
|
||||||
var player: Node3D = null
|
|
||||||
|
|
||||||
## The current player chunk coordinate.
|
|
||||||
var _player_chunk_coord: Vector3i = Vector3i.ZERO
|
|
||||||
|
|
||||||
## Map of loaded chunk coordinates to their scene nodes.
|
|
||||||
var _loaded_chunks: Dictionary = {}
|
|
||||||
|
|
||||||
## Queue of chunk coordinates pending load, sorted by distance from player.
|
|
||||||
var _load_queue: Array[Vector3i] = []
|
|
||||||
|
|
||||||
## Queue of chunk coordinates pending unload.
|
|
||||||
var _unload_queue: Array[Vector3i] = []
|
|
||||||
|
|
||||||
## Whether streaming is currently active (player is set and in game).
|
|
||||||
var is_active: bool = false
|
|
||||||
|
|
||||||
## The server RPC interface for chunk data. Set by the networking layer.
|
|
||||||
var _server_rpc: Object = null
|
|
||||||
|
|
||||||
## Internal: track which chunks are currently being loaded (to avoid duplicates).
|
|
||||||
var _loading_in_progress: Dictionary = {}
|
|
||||||
|
|
||||||
## Internal: time accumulator for throttled streaming updates.
|
|
||||||
var _update_accumulator: float = 0.0
|
|
||||||
|
|
||||||
## Internal: interval between streaming updates (seconds).
|
|
||||||
const UPDATE_INTERVAL: float = 0.1
|
|
||||||
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# Streaming is driven from _process (main thread) so we can safely
|
|
||||||
# manipulate the scene tree. No background thread is used.
|
|
||||||
set_process(true)
|
|
||||||
|
|
||||||
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
if not is_active or player == null:
|
|
||||||
return
|
|
||||||
|
|
||||||
_update_accumulator += delta
|
|
||||||
if _update_accumulator < UPDATE_INTERVAL:
|
|
||||||
return
|
|
||||||
_update_accumulator = 0.0
|
|
||||||
|
|
||||||
_update_streaming()
|
|
||||||
_process_load_queue()
|
|
||||||
_process_unload_queue()
|
|
||||||
streaming_updated.emit()
|
|
||||||
|
|
||||||
|
|
||||||
func _update_streaming() -> void:
|
|
||||||
if player == null or not is_inside_tree():
|
|
||||||
return
|
|
||||||
|
|
||||||
var current_coord: Vector3i = Chunk.coord_for_position(player.global_position)
|
|
||||||
if current_coord == _player_chunk_coord:
|
|
||||||
return
|
|
||||||
|
|
||||||
_player_chunk_coord = current_coord
|
|
||||||
_rebuild_queues()
|
|
||||||
|
|
||||||
|
|
||||||
func _rebuild_queues() -> void:
|
|
||||||
var target_set: Dictionary = _compute_target_chunks()
|
|
||||||
|
|
||||||
# Determine which chunks need to be loaded
|
|
||||||
var to_load: Array[Vector3i] = []
|
|
||||||
for coord in target_set:
|
|
||||||
if not _loaded_chunks.has(coord) and not _loading_in_progress.has(coord):
|
|
||||||
to_load.append(coord)
|
|
||||||
|
|
||||||
# Sort by distance from player (closest first)
|
|
||||||
to_load.sort_custom(_compare_distance)
|
|
||||||
_load_queue = to_load
|
|
||||||
|
|
||||||
# Determine which chunks need to be unloaded
|
|
||||||
var to_unload: Array[Vector3i] = []
|
|
||||||
for coord in _loaded_chunks:
|
|
||||||
if not target_set.has(coord):
|
|
||||||
to_unload.append(coord)
|
|
||||||
|
|
||||||
to_unload.sort_custom(_compare_distance)
|
|
||||||
_unload_queue = to_unload
|
|
||||||
|
|
||||||
|
|
||||||
func _compute_target_chunks() -> Dictionary:
|
|
||||||
"""Compute the set of chunk coordinates that should be loaded."""
|
|
||||||
var target: Dictionary = {}
|
|
||||||
var half: int = streaming_radius
|
|
||||||
for dx in range(-half, half + 1):
|
|
||||||
for dy in range(-half, half + 1):
|
|
||||||
for dz in range(-half, half + 1):
|
|
||||||
var coord: Vector3i = Vector3i(
|
|
||||||
_player_chunk_coord.x + dx,
|
|
||||||
_player_chunk_coord.y + dy,
|
|
||||||
_player_chunk_coord.z + dz
|
|
||||||
)
|
|
||||||
target[coord] = coord
|
|
||||||
return target
|
|
||||||
|
|
||||||
|
|
||||||
func _compare_distance(a: Vector3i, b: Vector3i) -> bool:
|
|
||||||
"""Compare chunk coordinates by distance from player chunk."""
|
|
||||||
var dist_a: int = _chunk_distance_squared(_player_chunk_coord, a)
|
|
||||||
var dist_b: int = _chunk_distance_squared(_player_chunk_coord, b)
|
|
||||||
return dist_a < dist_b
|
|
||||||
|
|
||||||
|
|
||||||
func _chunk_distance_squared(a: Vector3i, b: Vector3i) -> int:
|
|
||||||
var dx: int = a.x - b.x
|
|
||||||
var dy: int = a.y - b.y
|
|
||||||
var dz: int = a.z - b.z
|
|
||||||
return dx * dx + dy * dy + dz * dz
|
|
||||||
|
|
||||||
|
|
||||||
func _process_load_queue() -> void:
|
|
||||||
var count: int = 0
|
|
||||||
while count < max_loads_per_frame and not _load_queue.is_empty():
|
|
||||||
var coord: Vector3i = _load_queue.pop_front()
|
|
||||||
_load_chunk(coord)
|
|
||||||
count += 1
|
|
||||||
|
|
||||||
|
|
||||||
func _process_unload_queue() -> void:
|
|
||||||
var count: int = 0
|
|
||||||
while count < max_unloads_per_frame and not _unload_queue.is_empty():
|
|
||||||
var coord: Vector3i = _unload_queue.pop_front()
|
|
||||||
_unload_chunk(coord)
|
|
||||||
count += 1
|
|
||||||
|
|
||||||
|
|
||||||
func _load_chunk(coord: Vector3i) -> void:
|
|
||||||
if _loading_in_progress.has(coord):
|
|
||||||
return
|
|
||||||
|
|
||||||
_loading_in_progress[coord] = true
|
|
||||||
|
|
||||||
# Request chunk data from server via RPC
|
|
||||||
if _server_rpc != null and _server_rpc.has_method("request_chunk"):
|
|
||||||
_server_rpc.request_chunk(Chunk.build_key(
|
|
||||||
"", "", coord
|
|
||||||
))
|
|
||||||
else:
|
|
||||||
# Fallback: try to load from local cache or create empty chunk
|
|
||||||
_instantiate_chunk_scene(coord)
|
|
||||||
|
|
||||||
|
|
||||||
func _on_chunk_data_received(key: String, binary_data: PackedByteArray) -> void:
|
|
||||||
"""Called by the networking layer when chunk data arrives from server."""
|
|
||||||
var coord: Vector3i = _parse_coord_from_key(key)
|
|
||||||
if coord == null:
|
|
||||||
return
|
|
||||||
|
|
||||||
_loading_in_progress.erase(coord)
|
|
||||||
|
|
||||||
# Decode the binary chunk data
|
|
||||||
var chunk_data: ChunkDataDecoder.ChunkPayload = ChunkDataDecoder.decode_binary(binary_data)
|
|
||||||
if chunk_data == null:
|
|
||||||
chunk_load_failed.emit(coord, "Failed to decode chunk data")
|
|
||||||
return
|
|
||||||
|
|
||||||
# Instantiate the chunk scene with the decoded data
|
|
||||||
_instantiate_chunk_scene_with_data(coord, chunk_data)
|
|
||||||
|
|
||||||
|
|
||||||
func _on_chunk_load_error(coord: Vector3i, error_msg: String) -> void:
|
|
||||||
"""Called when the server reports a chunk load error."""
|
|
||||||
_loading_in_progress.erase(coord)
|
|
||||||
chunk_load_failed.emit(coord, error_msg)
|
|
||||||
|
|
||||||
|
|
||||||
func _instantiate_chunk_scene(coord: Vector3i) -> void:
|
|
||||||
"""Create an empty chunk scene for the given coordinate."""
|
|
||||||
var chunk_scene: ChunkScene = ChunkScene.new()
|
|
||||||
chunk_scene.coord = coord
|
|
||||||
chunk_scene.key = Chunk.build_key("", "", coord)
|
|
||||||
chunk_scene.bounds = Chunk.compute_bounds(coord)
|
|
||||||
_add_loaded_chunk(coord, chunk_scene)
|
|
||||||
|
|
||||||
|
|
||||||
func _instantiate_chunk_scene_with_data(coord: Vector3i, data: ChunkDataDecoder.ChunkPayload) -> void:
|
|
||||||
"""Create a chunk scene populated with server data."""
|
|
||||||
var chunk_scene: ChunkScene = ChunkScene.new()
|
|
||||||
chunk_scene.coord = coord
|
|
||||||
chunk_scene.key = data.key
|
|
||||||
chunk_scene.bounds = data.bounds
|
|
||||||
chunk_scene.format_version = data.format_version
|
|
||||||
chunk_scene.revision = data.revision
|
|
||||||
|
|
||||||
# Add tiles
|
|
||||||
for layer in data.tile_layers:
|
|
||||||
var tile_layer: TileLayer = TileLayer.new()
|
|
||||||
tile_layer.name = layer.name
|
|
||||||
tile_layer.layer_id = layer.layer_id
|
|
||||||
tile_layer.width = layer.width
|
|
||||||
tile_layer.height = layer.height
|
|
||||||
tile_layer.depth = layer.depth
|
|
||||||
tile_layer.palette = layer.palette
|
|
||||||
tile_layer.tiles = layer.tiles
|
|
||||||
chunk_scene.add_tile_layer(tile_layer)
|
|
||||||
|
|
||||||
# Add objects
|
|
||||||
for obj_data in data.objects:
|
|
||||||
var world_obj: WorldObject = WorldObject.new()
|
|
||||||
world_obj.id = obj_data.id
|
|
||||||
world_obj.type = obj_data.type
|
|
||||||
world_obj.asset_id = obj_data.asset_id
|
|
||||||
world_obj.position = obj_data.position
|
|
||||||
world_obj.rotation = obj_data.rotation
|
|
||||||
world_obj.scale = obj_data.scale
|
|
||||||
world_obj.properties = obj_data.properties
|
|
||||||
world_obj.is_dynamic = obj_data.dynamic
|
|
||||||
world_obj.flags = obj_data.flags
|
|
||||||
chunk_scene.add_object(world_obj)
|
|
||||||
|
|
||||||
# Add content flags
|
|
||||||
chunk_scene.content_flags = data.flags
|
|
||||||
|
|
||||||
_add_loaded_chunk(coord, chunk_scene)
|
|
||||||
|
|
||||||
|
|
||||||
func _add_loaded_chunk(coord: Vector3i, chunk_scene: Node) -> void:
|
|
||||||
_loaded_chunks[coord] = chunk_scene
|
|
||||||
add_child(chunk_scene)
|
|
||||||
_loading_in_progress.erase(coord)
|
|
||||||
chunk_loaded.emit(coord, chunk_scene)
|
|
||||||
|
|
||||||
|
|
||||||
func _unload_chunk(coord: Vector3i) -> void:
|
|
||||||
if not _loaded_chunks.has(coord):
|
|
||||||
return
|
|
||||||
|
|
||||||
var chunk_scene: Node = _loaded_chunks[coord]
|
|
||||||
if is_instance_valid(chunk_scene):
|
|
||||||
chunk_scene.queue_free()
|
|
||||||
|
|
||||||
_loaded_chunks.erase(coord)
|
|
||||||
chunk_unloaded.emit(coord)
|
|
||||||
|
|
||||||
|
|
||||||
func _on_player_position_changed() -> void:
|
|
||||||
"""Call this when the player position changes significantly."""
|
|
||||||
if player != null:
|
|
||||||
_update_streaming()
|
|
||||||
|
|
||||||
|
|
||||||
func set_server_rpc(rpc_interface: Object) -> void:
|
|
||||||
"""Set the server RPC interface for chunk requests."""
|
|
||||||
_server_rpc = rpc_interface
|
|
||||||
|
|
||||||
|
|
||||||
func get_loaded_chunk(coord: Vector3i) -> Node:
|
|
||||||
"""Get a loaded chunk scene by coordinate, or null if not loaded."""
|
|
||||||
return _loaded_chunks.get(coord, null)
|
|
||||||
|
|
||||||
|
|
||||||
func is_chunk_loaded(coord: Vector3i) -> bool:
|
|
||||||
"""Check if a chunk is currently loaded."""
|
|
||||||
return _loaded_chunks.has(coord)
|
|
||||||
|
|
||||||
|
|
||||||
func get_loaded_chunk_count() -> int:
|
|
||||||
"""Get the number of currently loaded chunks."""
|
|
||||||
return _loaded_chunks.size()
|
|
||||||
|
|
||||||
|
|
||||||
func get_all_loaded_coords() -> Array[Vector3i]:
|
|
||||||
"""Get all currently loaded chunk coordinates."""
|
|
||||||
var coords: Array[Vector3i] = []
|
|
||||||
for key in _loaded_chunks:
|
|
||||||
coords.append(key)
|
|
||||||
return coords
|
|
||||||
|
|
||||||
|
|
||||||
func force_reload_chunk(coord: Vector3i) -> void:
|
|
||||||
"""Force reload a specific chunk (e.g., after server update)."""
|
|
||||||
if _loaded_chunks.has(coord):
|
|
||||||
_unload_chunk(coord)
|
|
||||||
if not _loading_in_progress.has(coord):
|
|
||||||
_load_chunk(coord)
|
|
||||||
|
|
||||||
|
|
||||||
func clear_all_chunks() -> void:
|
|
||||||
"""Unload all chunks immediately."""
|
|
||||||
var coords: Array[Vector3i] = get_all_loaded_coords()
|
|
||||||
for coord in coords:
|
|
||||||
_unload_chunk(coord)
|
|
||||||
_load_queue.clear()
|
|
||||||
_unload_queue.clear()
|
|
||||||
|
|
||||||
|
|
||||||
func _parse_coord_from_key(key: String) -> Variant:
|
|
||||||
"""Parse chunk coordinate from a canonical chunk key."""
|
|
||||||
var parts: Array[String] = key.split(":")
|
|
||||||
if parts.size() < 5:
|
|
||||||
return null
|
|
||||||
return Vector3i(
|
|
||||||
int(parts[2]),
|
|
||||||
int(parts[3]),
|
|
||||||
int(parts[4])
|
|
||||||
)
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://8yokqwe23c23
|
|
||||||
@@ -1,68 +0,0 @@
|
|||||||
class_name DynamicObjectNode
|
|
||||||
extends Node3D
|
|
||||||
## A visual representation of a dynamic (spawnable) world object template.
|
|
||||||
##
|
|
||||||
## This node is instantiated by [ChunkScene] for each dynamic [WorldObject].
|
|
||||||
## Dynamic objects are stored as *templates* in the chunk; their runtime state
|
|
||||||
## (position, health, inventory) is managed by the entity system, not by this
|
|
||||||
## node. This node renders the template's visual representation so the object
|
|
||||||
## is visible in the world.
|
|
||||||
##
|
|
||||||
## ## Structure
|
|
||||||
##
|
|
||||||
## ```
|
|
||||||
## DynamicObjectNode (Node3D)
|
|
||||||
## └── MeshInstance3D # the object's visual mesh
|
|
||||||
## ```
|
|
||||||
|
|
||||||
## The world object data this node represents.
|
|
||||||
var world_object: WorldObject = null
|
|
||||||
|
|
||||||
## The loaded mesh instance (or placeholder).
|
|
||||||
var _mesh_instance: MeshInstance3D = null
|
|
||||||
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
if world_object == null:
|
|
||||||
return
|
|
||||||
_load_mesh()
|
|
||||||
|
|
||||||
|
|
||||||
## Load and attach the object's mesh.
|
|
||||||
func _load_mesh() -> void:
|
|
||||||
_mesh_instance = MeshInstance3D.new()
|
|
||||||
_mesh_instance.name = "mesh"
|
|
||||||
|
|
||||||
var mesh := _load_asset_mesh(world_object.asset_id)
|
|
||||||
if mesh == null:
|
|
||||||
mesh = _make_placeholder_mesh()
|
|
||||||
|
|
||||||
_mesh_instance.mesh = mesh
|
|
||||||
add_child(_mesh_instance)
|
|
||||||
|
|
||||||
|
|
||||||
## Attempt to load a mesh from the asset path.
|
|
||||||
func _load_asset_mesh(asset_id: String) -> Mesh:
|
|
||||||
if asset_id.is_empty():
|
|
||||||
return null
|
|
||||||
var path := "res://assets/%s" % asset_id
|
|
||||||
if ResourceLoader.exists(path):
|
|
||||||
var res := load(path)
|
|
||||||
if res is Mesh:
|
|
||||||
return res
|
|
||||||
return null
|
|
||||||
|
|
||||||
|
|
||||||
## Create a simple placeholder sphere mesh when the real asset is unavailable.
|
|
||||||
func _make_placeholder_mesh() -> Mesh:
|
|
||||||
var mesh := SphereMesh.new()
|
|
||||||
mesh.radius = 0.5
|
|
||||||
mesh.height = 1.0
|
|
||||||
return mesh
|
|
||||||
|
|
||||||
|
|
||||||
## Get the world object's display name.
|
|
||||||
func get_display_name() -> String:
|
|
||||||
if world_object == null:
|
|
||||||
return ""
|
|
||||||
return world_object.get_display_name()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://dyjqcstdnr4u1
|
|
||||||
@@ -0,0 +1,13 @@
|
|||||||
|
extends Control
|
||||||
|
|
||||||
|
|
||||||
|
func _ready():
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
func _on_play_button_pressed():
|
||||||
|
get_tree().change_scene_to_file("res://scenes/game.tscn")
|
||||||
|
|
||||||
|
|
||||||
|
func _on_quit_button_pressed():
|
||||||
|
get_tree().quit()
|
||||||
@@ -1,67 +0,0 @@
|
|||||||
class_name StaticObjectNode
|
|
||||||
extends Node3D
|
|
||||||
## A visual representation of a static world object within a chunk.
|
|
||||||
##
|
|
||||||
## This node is instantiated by [ChunkScene] for each static (non-dynamic)
|
|
||||||
## [WorldObject]. It renders the object's mesh (referenced by `asset_id`) at
|
|
||||||
## the object's transform. If the asset is not yet loaded, a placeholder mesh
|
|
||||||
## is shown.
|
|
||||||
##
|
|
||||||
## ## Structure
|
|
||||||
##
|
|
||||||
## ```
|
|
||||||
## StaticObjectNode (Node3D)
|
|
||||||
## └── MeshInstance3D # the object's visual mesh
|
|
||||||
## ```
|
|
||||||
|
|
||||||
## The world object data this node represents.
|
|
||||||
var world_object: WorldObject = null
|
|
||||||
|
|
||||||
## The loaded mesh instance (or placeholder).
|
|
||||||
var _mesh_instance: MeshInstance3D = null
|
|
||||||
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
if world_object == null:
|
|
||||||
return
|
|
||||||
_load_mesh()
|
|
||||||
|
|
||||||
|
|
||||||
## Load and attach the object's mesh.
|
|
||||||
func _load_mesh() -> void:
|
|
||||||
_mesh_instance = MeshInstance3D.new()
|
|
||||||
_mesh_instance.name = "mesh"
|
|
||||||
|
|
||||||
# Try to load the asset by its id (path). Fall back to a placeholder.
|
|
||||||
var mesh := _load_asset_mesh(world_object.asset_id)
|
|
||||||
if mesh == null:
|
|
||||||
mesh = _make_placeholder_mesh()
|
|
||||||
|
|
||||||
_mesh_instance.mesh = mesh
|
|
||||||
add_child(_mesh_instance)
|
|
||||||
|
|
||||||
|
|
||||||
## Attempt to load a mesh from the asset path.
|
|
||||||
func _load_asset_mesh(asset_id: String) -> Mesh:
|
|
||||||
if asset_id.is_empty():
|
|
||||||
return null
|
|
||||||
var path := "res://assets/%s" % asset_id
|
|
||||||
if ResourceLoader.exists(path):
|
|
||||||
var res := load(path)
|
|
||||||
if res is Mesh:
|
|
||||||
return res
|
|
||||||
return null
|
|
||||||
|
|
||||||
|
|
||||||
## Create a simple placeholder box mesh when the real asset is unavailable.
|
|
||||||
func _make_placeholder_mesh() -> Mesh:
|
|
||||||
var mesh := BoxMesh.new()
|
|
||||||
mesh.size = Vector3(1.0, 1.0, 1.0)
|
|
||||||
return mesh
|
|
||||||
|
|
||||||
|
|
||||||
## Get the world object's display name.
|
|
||||||
func get_display_name() -> String:
|
|
||||||
if world_object == null:
|
|
||||||
return ""
|
|
||||||
return world_object.get_display_name()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://chf6mruev1kc4
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
class_name TileDef
|
|
||||||
extends RefCounted
|
|
||||||
## A single tile definition (palette entry) within a tile layer.
|
|
||||||
##
|
|
||||||
## Maps a tile ID to its asset reference and gameplay flags. See
|
|
||||||
## docs/architecture/world.md §3.2.
|
|
||||||
|
|
||||||
## Tile ID (index into the layer palette). 0 is reserved for empty/air.
|
|
||||||
var id: int = 0
|
|
||||||
|
|
||||||
## Reference to the tile/terrain asset.
|
|
||||||
var asset_id: String = ""
|
|
||||||
|
|
||||||
## Whether this tile has collision.
|
|
||||||
var solid: bool = false
|
|
||||||
|
|
||||||
## Bitmask flags: bit 0 = walkable, bit 1 = climbable, bit 2 = liquid.
|
|
||||||
var flags: int = 0
|
|
||||||
|
|
||||||
## Number of visual variants for this tile.
|
|
||||||
var variants: int = 1
|
|
||||||
|
|
||||||
|
|
||||||
func _init(p_id: int = 0, p_asset_id: String = "", p_solid: bool = false,
|
|
||||||
p_flags: int = 0, p_variants: int = 1) -> void:
|
|
||||||
id = p_id
|
|
||||||
asset_id = p_asset_id
|
|
||||||
solid = p_solid
|
|
||||||
flags = p_flags
|
|
||||||
variants = p_variants
|
|
||||||
|
|
||||||
|
|
||||||
func is_walkable() -> bool:
|
|
||||||
return (flags & 0x01) != 0
|
|
||||||
|
|
||||||
|
|
||||||
func is_climbable() -> bool:
|
|
||||||
return (flags & 0x02) != 0
|
|
||||||
|
|
||||||
|
|
||||||
func is_liquid() -> bool:
|
|
||||||
return (flags & 0x04) != 0
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://bavmpbmthilbx
|
|
||||||
@@ -1,83 +0,0 @@
|
|||||||
class_name TileLayer
|
|
||||||
extends RefCounted
|
|
||||||
## A single tile layer within a chunk.
|
|
||||||
##
|
|
||||||
## Holds the dense grid of tile IDs, the palette mapping tile IDs to tile
|
|
||||||
## definitions, and the layer metadata. This is the runtime representation of
|
|
||||||
## the `TileLayer` from the chunk data format (see docs/architecture/world.md
|
|
||||||
## §3.2).
|
|
||||||
|
|
||||||
## Layer name (e.g. "ground", "walls", "decor").
|
|
||||||
var name: String = ""
|
|
||||||
|
|
||||||
## Numeric layer id, unique within the chunk.
|
|
||||||
var layer_id: int = 0
|
|
||||||
|
|
||||||
## Grid dimensions in tiles.
|
|
||||||
var width: int = 0
|
|
||||||
var height: int = 0
|
|
||||||
var depth: int = 1
|
|
||||||
|
|
||||||
## Palette mapping tile IDs to tile definitions (shared per layer).
|
|
||||||
var palette: Array[TileDef] = []
|
|
||||||
|
|
||||||
## Dense, row-major tile IDs. Length = width * height * depth.
|
|
||||||
var tiles: PackedInt32Array = PackedInt32Array()
|
|
||||||
|
|
||||||
|
|
||||||
func _init(
|
|
||||||
p_layer_name: String = "",
|
|
||||||
p_layer_id: int = 0,
|
|
||||||
p_width: int = 0,
|
|
||||||
p_height: int = 0,
|
|
||||||
p_depth: int = 1
|
|
||||||
) -> void:
|
|
||||||
name = p_layer_name
|
|
||||||
layer_id = p_layer_id
|
|
||||||
width = p_width
|
|
||||||
height = p_height
|
|
||||||
depth = p_depth
|
|
||||||
|
|
||||||
|
|
||||||
## Total number of tiles in this layer.
|
|
||||||
func tile_count() -> int:
|
|
||||||
return width * height * depth
|
|
||||||
|
|
||||||
|
|
||||||
## Get the tile ID at (x, y, z). Returns 0 (empty) for out-of-bounds.
|
|
||||||
func get_tile(x: int, y: int, z: int = 0) -> int:
|
|
||||||
if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
|
|
||||||
return 0
|
|
||||||
var idx := (z * height + y) * width + x
|
|
||||||
if idx < tiles.size():
|
|
||||||
return tiles[idx]
|
|
||||||
return 0
|
|
||||||
|
|
||||||
|
|
||||||
## Set the tile ID at (x, y, z). No-op if out of bounds.
|
|
||||||
func set_tile(x: int, y: int, z: int, tile_id: int) -> void:
|
|
||||||
if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
|
|
||||||
return
|
|
||||||
var idx := (z * height + y) * width + x
|
|
||||||
if idx < tiles.size():
|
|
||||||
tiles[idx] = tile_id
|
|
||||||
|
|
||||||
|
|
||||||
## Get the tile definition for a tile ID, or null if not in the palette.
|
|
||||||
func get_tile_def(tile_id: int) -> TileDef:
|
|
||||||
for def in palette:
|
|
||||||
if def.id == tile_id:
|
|
||||||
return def
|
|
||||||
return null
|
|
||||||
|
|
||||||
|
|
||||||
## Whether the tile at (x, y, z) is solid (collision).
|
|
||||||
func is_solid(x: int, y: int, z: int = 0) -> bool:
|
|
||||||
var def := get_tile_def(get_tile(x, y, z))
|
|
||||||
return def != null and def.solid
|
|
||||||
|
|
||||||
|
|
||||||
## Whether the tile at (x, y, z) is walkable.
|
|
||||||
func is_walkable(x: int, y: int, z: int = 0) -> bool:
|
|
||||||
var def := get_tile_def(get_tile(x, y, z))
|
|
||||||
return def != null and def.is_walkable()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://came2ygke3ajs
|
|
||||||
@@ -1,112 +0,0 @@
|
|||||||
class_name TileLayerNode
|
|
||||||
extends Node3D
|
|
||||||
## A visual representation of a single tile layer within a chunk.
|
|
||||||
##
|
|
||||||
## This node is instantiated by [ChunkScene] for each tile layer in a chunk.
|
|
||||||
## It renders the layer's tiles as instanced meshes (one per tile definition
|
|
||||||
## in the palette) using [MultiMeshInstance3D] for efficiency.
|
|
||||||
##
|
|
||||||
## ## Structure
|
|
||||||
##
|
|
||||||
## ```
|
|
||||||
## TileLayerNode (Node3D)
|
|
||||||
## └── MultiMeshInstance3D # one per palette entry (tile definition)
|
|
||||||
## ```
|
|
||||||
|
|
||||||
## The tile layer data this node renders.
|
|
||||||
var tile_layer: TileLayer = null
|
|
||||||
|
|
||||||
## The chunk coordinate this layer belongs to (for world positioning).
|
|
||||||
var chunk_coord: Vector3i = Vector3i.ZERO
|
|
||||||
|
|
||||||
## Tile size in world units (each tile is 1x1x1).
|
|
||||||
const TILE_SIZE: float = 1.0
|
|
||||||
|
|
||||||
## Cache of MultiMeshInstance3D nodes, keyed by tile definition id.
|
|
||||||
var _mesh_instances: Dictionary = {}
|
|
||||||
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
if tile_layer == null:
|
|
||||||
return
|
|
||||||
_build_meshes()
|
|
||||||
|
|
||||||
|
|
||||||
## Build the MultiMesh instances for each tile definition in the palette.
|
|
||||||
func _build_meshes() -> void:
|
|
||||||
for tile_def in tile_layer.palette:
|
|
||||||
if tile_def.id == 0:
|
|
||||||
continue # Tile 0 is "empty/air", no mesh needed
|
|
||||||
_create_mesh_for_tile(tile_def)
|
|
||||||
|
|
||||||
|
|
||||||
func _create_mesh_for_tile(tile_def: TileDef) -> void:
|
|
||||||
# Count how many cells use this tile definition
|
|
||||||
var count := 0
|
|
||||||
for tile_id in tile_layer.tiles:
|
|
||||||
if tile_id == tile_def.id:
|
|
||||||
count += 1
|
|
||||||
|
|
||||||
if count == 0:
|
|
||||||
return
|
|
||||||
|
|
||||||
var multi_mesh := MultiMesh.new()
|
|
||||||
multi_mesh.transform_format = MultiMesh.TRANSFORM_3D
|
|
||||||
multi_mesh.mesh = _make_unit_cube_mesh()
|
|
||||||
multi_mesh.instance_count = count
|
|
||||||
|
|
||||||
var instance_idx := 0
|
|
||||||
for z in range(tile_layer.depth):
|
|
||||||
for y in range(tile_layer.height):
|
|
||||||
for x in range(tile_layer.width):
|
|
||||||
var tile_id := tile_layer.get_tile(x, y, z)
|
|
||||||
if tile_id != tile_def.id:
|
|
||||||
continue
|
|
||||||
var world_pos := _tile_to_world(x, y, z)
|
|
||||||
var xform := Transform3D(Basis(), world_pos)
|
|
||||||
multi_mesh.set_instance_transform(instance_idx, xform)
|
|
||||||
instance_idx += 1
|
|
||||||
|
|
||||||
var mesh_instance := MultiMeshInstance3D.new()
|
|
||||||
mesh_instance.multimesh = multi_mesh
|
|
||||||
mesh_instance.name = "tiles_%d" % tile_def.id
|
|
||||||
add_child(mesh_instance)
|
|
||||||
_mesh_instances[tile_def.id] = mesh_instance
|
|
||||||
|
|
||||||
|
|
||||||
## Convert a tile grid coordinate to a world-space position (center of tile).
|
|
||||||
func _tile_to_world(x: int, y: int, z: int) -> Vector3:
|
|
||||||
var origin := Vector3(
|
|
||||||
chunk_coord.x * tile_layer.width,
|
|
||||||
chunk_coord.y * tile_layer.height,
|
|
||||||
chunk_coord.z * tile_layer.depth
|
|
||||||
)
|
|
||||||
return origin + Vector3(
|
|
||||||
x * TILE_SIZE + TILE_SIZE * 0.5,
|
|
||||||
y * TILE_SIZE + TILE_SIZE * 0.5,
|
|
||||||
z * TILE_SIZE + TILE_SIZE * 0.5
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
## Create a simple unit cube mesh for tile rendering.
|
|
||||||
func _make_unit_cube_mesh() -> Mesh:
|
|
||||||
var mesh := BoxMesh.new()
|
|
||||||
mesh.size = Vector3(TILE_SIZE, TILE_SIZE, TILE_SIZE)
|
|
||||||
return mesh
|
|
||||||
|
|
||||||
|
|
||||||
## Get the tile definition at a grid position, or null if empty.
|
|
||||||
func get_tile_def_at(x: int, y: int, z: int = 0) -> TileDef:
|
|
||||||
if tile_layer == null:
|
|
||||||
return null
|
|
||||||
var tile_id := tile_layer.get_tile(x, y, z)
|
|
||||||
if tile_id == 0:
|
|
||||||
return null
|
|
||||||
return tile_layer.get_tile_def(tile_id)
|
|
||||||
|
|
||||||
|
|
||||||
## Clear all rendered meshes.
|
|
||||||
func clear() -> void:
|
|
||||||
for child in get_children():
|
|
||||||
child.queue_free()
|
|
||||||
_mesh_instances.clear()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://d1x05tq8h43gm
|
|
||||||
@@ -1,135 +0,0 @@
|
|||||||
class_name WorldObject
|
|
||||||
extends RefCounted
|
|
||||||
## A world object (static or dynamic) within a chunk.
|
|
||||||
##
|
|
||||||
## This is the runtime representation of a WorldObject from the chunk data
|
|
||||||
## format (see docs/architecture/world.md §3.3). It holds the object's
|
|
||||||
## identity, transform, properties, and moderation flags.
|
|
||||||
|
|
||||||
## Stable object ID, unique within the chunk.
|
|
||||||
var id: String = ""
|
|
||||||
|
|
||||||
## Object type (e.g. "prop", "interactable", "spawn_point", "door").
|
|
||||||
var type: String = ""
|
|
||||||
|
|
||||||
## Reference to the object's mesh/glTF asset.
|
|
||||||
var asset_id: String = ""
|
|
||||||
|
|
||||||
## World-space position.
|
|
||||||
var position: Vector3 = Vector3.ZERO
|
|
||||||
|
|
||||||
## World-space rotation as a quaternion (x, y, z, w).
|
|
||||||
var rotation: Vector4 = Vector4(0, 0, 0, 1)
|
|
||||||
|
|
||||||
## World-space scale.
|
|
||||||
var scale: Vector3 = Vector3.ONE
|
|
||||||
|
|
||||||
## Type-specific key/value properties.
|
|
||||||
var properties: Dictionary = {}
|
|
||||||
|
|
||||||
## Whether this is a spawnable dynamic entity (true) or static (false).
|
|
||||||
var is_dynamic: bool = false
|
|
||||||
|
|
||||||
## Per-object content moderation flags.
|
|
||||||
var flags: ChunkDataDecoder.ContentFlags = ChunkDataDecoder.ContentFlags.new()
|
|
||||||
|
|
||||||
## Whether this object has been modified locally.
|
|
||||||
var is_dirty: bool = false
|
|
||||||
|
|
||||||
|
|
||||||
func _init(
|
|
||||||
p_id: String = "",
|
|
||||||
p_type: String = "",
|
|
||||||
p_asset_id: String = "",
|
|
||||||
p_position: Vector3 = Vector3.ZERO,
|
|
||||||
p_rotation: Vector4 = Vector4(0, 0, 0, 1),
|
|
||||||
p_scale: Vector3 = Vector3.ONE,
|
|
||||||
p_properties: Dictionary = {},
|
|
||||||
p_dynamic: bool = false,
|
|
||||||
p_flags: ChunkDataDecoder.ContentFlags = null
|
|
||||||
) -> void:
|
|
||||||
id = p_id
|
|
||||||
type = p_type
|
|
||||||
asset_id = p_asset_id
|
|
||||||
position = p_position
|
|
||||||
rotation = p_rotation
|
|
||||||
scale = p_scale
|
|
||||||
properties = p_properties
|
|
||||||
is_dynamic = p_dynamic
|
|
||||||
if p_flags != null:
|
|
||||||
flags = p_flags
|
|
||||||
|
|
||||||
|
|
||||||
## Get a property value by key.
|
|
||||||
func get_property(key: String) -> Variant:
|
|
||||||
return properties.get(key)
|
|
||||||
|
|
||||||
|
|
||||||
## Set a property value.
|
|
||||||
func set_property(key: String, value: Variant) -> void:
|
|
||||||
properties[key] = value
|
|
||||||
is_dirty = true
|
|
||||||
|
|
||||||
|
|
||||||
## Check if this object is walkable (based on properties).
|
|
||||||
func is_walkable() -> bool:
|
|
||||||
return properties.get("walkable", true)
|
|
||||||
|
|
||||||
|
|
||||||
## Check if this object is climbable (based on properties).
|
|
||||||
func is_climbable() -> bool:
|
|
||||||
return properties.get("climbable", false)
|
|
||||||
|
|
||||||
|
|
||||||
## Check if this object is interactable.
|
|
||||||
func is_interactable() -> bool:
|
|
||||||
return type == "interactable" or properties.get("interactable", false)
|
|
||||||
|
|
||||||
|
|
||||||
## Get the object's display name.
|
|
||||||
func get_display_name() -> String:
|
|
||||||
return properties.get("display_name", id)
|
|
||||||
|
|
||||||
|
|
||||||
## Serialize this object to a dictionary (for networking).
|
|
||||||
func to_dict() -> Dictionary:
|
|
||||||
return {
|
|
||||||
"id": id,
|
|
||||||
"type": type,
|
|
||||||
"asset_id": asset_id,
|
|
||||||
"position": [position.x, position.y, position.z],
|
|
||||||
"rotation": [rotation.x, rotation.y, rotation.z, rotation.w],
|
|
||||||
"scale": [scale.x, scale.y, scale.z],
|
|
||||||
"properties": properties,
|
|
||||||
"dynamic": is_dynamic,
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
## Create a WorldObject from a dictionary (for networking).
|
|
||||||
static func from_dict(d: Dictionary) -> WorldObject:
|
|
||||||
var pos := Vector3(
|
|
||||||
d.get("position", [0, 0, 0])[0],
|
|
||||||
d.get("position", [0, 0, 0])[1],
|
|
||||||
d.get("position", [0, 0, 0])[2]
|
|
||||||
)
|
|
||||||
var rot := Vector4(
|
|
||||||
d.get("rotation", [0, 0, 0, 1])[0],
|
|
||||||
d.get("rotation", [0, 0, 0, 1])[1],
|
|
||||||
d.get("rotation", [0, 0, 0, 1])[2],
|
|
||||||
d.get("rotation", [0, 0, 0, 1])[3]
|
|
||||||
)
|
|
||||||
var scl := Vector3(
|
|
||||||
d.get("scale", [1, 1, 1])[0],
|
|
||||||
d.get("scale", [1, 1, 1])[1],
|
|
||||||
d.get("scale", [1, 1, 1])[2]
|
|
||||||
)
|
|
||||||
return WorldObject.new(
|
|
||||||
d.get("id", ""),
|
|
||||||
d.get("type", ""),
|
|
||||||
d.get("asset_id", ""),
|
|
||||||
pos,
|
|
||||||
rot,
|
|
||||||
scl,
|
|
||||||
d.get("properties", {}),
|
|
||||||
d.get("dynamic", false),
|
|
||||||
)
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://cxut2ghbsvobn
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
Godot Engine v4.6.2.stable.official.71f334935 - https://godotengine.org
|
|
||||||
|
|
||||||
roundtrip bounds.position = (0.0, 0.0, 0.0) (expected (0.5, 1.5, 2.5))
|
|
||||||
roundtrip coord = (0, 0, 0) (expected (1, 2, 3))
|
|
||||||
format_version present? -> <null>
|
|
||||||
version field -> 1
|
|
||||||
SCRIPT ERROR: Invalid assignment of property or key 'properties' with value of type 'bool' on a base object of type 'RefCounted (WorldObjectData)'.
|
|
||||||
at: _parse_object_section (res://scripts/chunk_data_decoder.gd:407)
|
|
||||||
GDScript backtrace (most recent call first):
|
|
||||||
[0] _parse_object_section (res://scripts/chunk_data_decoder.gd:407)
|
|
||||||
[1] _init (res://test_review.gd:25)
|
|
||||||
SCRIPT ERROR: Out of bounds get index '0' (on base: 'Array[WorldObjectData]')
|
|
||||||
at: _init (res://test_review.gd:26)
|
|
||||||
GDScript backtrace (most recent call first):
|
|
||||||
[0] _init (res://test_review.gd:26)
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
extends SceneTree
|
|
||||||
|
|
||||||
func _init() -> void:
|
|
||||||
# 1. float32 encode/decode
|
|
||||||
var b: PackedByteArray = ChunkDataDecoder._write_float32(0.5)
|
|
||||||
print("float32(0.5) bytes = ", b, " (expected 00 00 00 3f)")
|
|
||||||
var decoded_f: float = ChunkDataDecoder._read_float32(PackedByteArray([0x00, 0x00, 0x00, 0x3f]), 0)
|
|
||||||
print("read_float32 of 0x3f000000 = ", decoded_f, " (expected 0.5)")
|
|
||||||
|
|
||||||
# 2. metadata section wrapping: inspect first bytes of encoded payload
|
|
||||||
var payload: ChunkDataDecoder.ChunkPayload = ChunkDataDecoder.ChunkPayload.new()
|
|
||||||
payload.world_id = "w"
|
|
||||||
payload.room_id = "r"
|
|
||||||
payload.coord = Vector3i(1, 2, 3)
|
|
||||||
var meta: PackedByteArray = ChunkDataDecoder._build_metadata_section(payload)
|
|
||||||
print("metadata section first 12 bytes = ", meta.slice(0, 12))
|
|
||||||
|
|
||||||
# 3. properties parse with empty-ish string
|
|
||||||
var props_str := "{}"
|
|
||||||
var val = JSON.parse_string(props_str) or {}
|
|
||||||
print("'JSON.parse_string(props_str) or {{}}' type = ", typeof(val), " value = ", val)
|
|
||||||
quit()
|
|
||||||
Reference in New Issue
Block a user