Skip to content

Harbour Kit v1 - Asset Metadata Schema

Engine-ready metadata for Godot import · One YAML file per smart prop / NPC

Purpose

Assets are not just PNGs. The Mission Engine and Visual Engine need metadata to place repair points, FX anchors, and NPC states.

Store metadata alongside sprites:

public/assets/world/harbour-kit/
├── tiles/
├── characters/
├── props/
├── fx/
└── meta/
    ├── fishing_net.yaml
    ├── fisherman.yaml
    └── ...

Prop schema

id: fishing_net
category: mission_prop
archetype: repairable          # repairable | revealable | fillable | progressive | static
states:
  problem: fishing_net_broken
  complete: fishing_net_repaired
allowedPatterns:
  - repair_object
allowedMechanics:
  - missing_letter
  - spell_word
allowedUiModes:
  - focus_object
effects:
  correct:
    - letter_fly_to_target
    - stitch_line
  complete:
    - sparkle_success
  wrong:
    - wrong_wobble
anchors:
  repairPoints:
    - id: top_left
      x: 120
      y: 45
    - id: centre
      x: 180
      y: 90
  interactionZone:
    x: 80
    y: 40
    w: 160
    h: 100
tileSize: 48

NPC schema

id: fisherman
category: npc
defaultLocation: harbour_pier
states:
  idle: fisherman_idle
  talk: fisherman_talk
  worried: fisherman_worried
  point: fisherman_point
  happy: fisherman_happy
missionDomains:
  - fishing
  - sea
  - delivery
preferredVerbs:
  - repair
  - guide
  - deliver
  - sort
preferredProps:
  - fishing_net
  - fish_token
  - basket
dialogueTone: warm_practical

Tile schema

id: water_tile_base
category: terrain
tileSize: 48
seamless: true
edges:
  - water_edge_top
  - water_edge_bottom
  - sand_to_water_edge_top
variants:
  - water_tile_variant_01

FX schema

id: stitch_line
category: fx
frames: 8
layer: above_prop
loops: false
allowedArchetypes:
  - repairable

Map zone schema (harbour_map_zones.yaml)

zones:
  - id: shore_bottle
    bounds: { x: 2, y: 8, w: 4, h: 3 }
    triggers:
      - bottle_pickup
  - id: pier_fisherman
    bounds: { x: 10, y: 6, w: 6, h: 4 }
    npc: fisherman
lockedPaths:
  - id: sea_route
    untilWorldState: harbour_ready

M0 assets (minimal metadata)

For Milestone 0, only static placement — full YAML optional until M1:

Asset Metadata needed for M0
water_tile_base tile schema
sand_tile_base tile schema
dock_tile_base tile schema
captain_idle_down none (character scene)
message_bottle interaction zone when placed on map
sparkle_indicator fx schema (loop)