boatgame/docs/adding-content.md

Adding content — quick checklist

Rough working notes. Verify against the scripts if anything looks off; file references are the source of truth.

1. Adding a new weapon

The pipeline is def-driven: AmmoDef (what it fires) → WeaponDef (the gun) → weapon scene (the visible mount). Scenes are shared — mark12.tscn is used by both mark12.tres and bofors.tres. Only build a new scene for a new look.

1. AmmoDef — new .tres in resources/ammo/ (script: scripts/resource_definitions/ammo_def.gd). Fields: projectile_scene (usually shell.tscn), damage, muzzle_speed, gravity_scale, lifetime, display_name.
2. WeaponDef — new .tres in resources/weapons/ (script: scripts/resource_definitions/weapon_def.gd). Fields: weapon_scene (required — WeaponSlot.can_mount() rejects a def without one; reuse mark12.tscn unless you made a new scene), ammo, fire_interval, muzzle_speed_scale (barrel-length multiplier on ammo speed), size / type (slot gating), traverse/elevation speeds and elevation limits.
3. Weapon scene (only if it needs a new look) — structure per mark12.tscn / scripts/weapon.gd:
   • Root Node3D with scripts/weapon.gd.
   • %Yaw (Node3D, unique name) — rotates horizontally. Optional: omit it and the weapon is a fixed mount (no aiming, fires along the muzzle).
   • %Pitch (Node3D, unique name) under Yaw — barrel elevation. Also optional (yaw-only mount if omitted).
   • %Muzzle (Marker3D, unique name) at the barrel tip, -Z pointing out of the barrel. Required — weapon.gd hard-references it.
   • %Hitbox (AnimatableBody3D, unique name) under Yaw, with a CollisionShape3D. Sync To Physics must be UNTICKED — with it on the collider does not follow the moving boat. Collision layer = subsystems (7) only, collision mask = empty. Projectiles get a collision exception with the shooter's hitboxes at fire time.
   • Leave the root's def export EMPTY. The mounting WeaponSlot assigns it (weapon_slot.gd mount()). A scene referencing its own def is infinite recursion (def → scene → def …).
4. Put it on a boat — add an entry to the Boat's loadout dictionary (scripts/boat.gd): key = the WeaponSlot node's exact name (StringName), value = the WeaponDef. Boat._ready() mounts everything. The slot's allowed_sizes / allowed_types must contain the def's size / type or mount() warns and refuses.

New projectile scenes: root must use scripts/projectile.gd (or replicate it) — it self-registers into shift_with_origin and calls reset_physics_interpolation() on launch. Copy shell.tscn's physics setup: layer 4 (projectiles), mask = terrain+player+enemies, continuous_cd on, contact_monitor on with max_contacts_reported ≥ 1.

2. Setting up a boat scene

Template: boat.tscn.

1. Root: RigidBody3D with scripts/boat.gd (extends scripts/floating_body.gd).
   • Group: shift_with_origin (set in the scene). The boats group is joined automatically in Boat._ready() — don't add it by hand.
   • Collision layer: player (2) or enemies (3).
   • Set mass — all handling forces scale with it, so handling stays the same across masses; mass mostly matters for collisions.
2. Children: MeshInstance3D + CollisionShape3D. Never scale physics nodes — set sizes on the mesh/shape resources themselves.
3. Buoyancy tuning (exports from floating_body.gd):
   • buoyancy (multiple of gravity when fully submerged; >1 floats), full_force_depth, water_drag, water_angular_drag, probe_damping.
   • Probe placement: probe_extents (half-width, height, half-length) + probe_grid (columns × rows). A grid axis of 1 is valid (centerline).
   • Any Marker3D direct children override the generated grid and become the probes — also means: don't park unrelated Marker3Ds directly under the boat root.
4. Handling exports on boat.gd: engine_power, reverse_ratio, throttle_response, rudder_strength, keel_grip.
5. Weapon mounts: child Node3Ds with scripts/weapon_slot.gd, positioned and rotated as the mount points (e.g. stern mount rotated 180°). Set allowed_sizes / allowed_types per slot (defaults: MEDIUM, BALLISTIC).
6. loadout dict on the root: slot node name → WeaponDef (see section 1). Keys must match the node names exactly.
7. weapon_groups: group id → array of slot names. Group 0 is auto-built in _ready() (all slots) — any editor value for it is ignored.

3. Other things to keep in mind

• Tabs, never spaces, for all GDScript.
• @export = static configuration only. Runtime-controlled references are plain var with a # Controlled by PlayerController style comment; internals use _prefix.
• Collision layers: 1 terrain, 2 player, 3 enemies, 4 projectiles, 5 pickups, 6 water, 7 subsystems (see project.godot [layer_names]). Water is query-only — surface/contact logic goes through Ocean.get_wave_height(), never a collider (that's how floating_body.gd does buoyancy).
• Wave math is dual-implemented: shaders/ocean.gdshader (rendering) and scripts/ocean.gd (physics). Any wave change goes in BOTH. Never set_shader_parameter on the water material from gameplay code — use Ocean's properties.
• Origin shifting is active. Free-moving objects (projectiles, debris, anything not parented to a shifted node) must join shift_with_origin — prefer add_to_group() in _ready(). Never cache world positions across frames; for true world-space positions use WorldManager.true_position().
• Physics interpolation is ON. Every deliberate teleport needs a reset_physics_interpolation() chaser or it renders as a smear.
• Boats never read Input. Controllers write intents: desired_throttle, steer_input, fire_intents, aim_point.
• Inspector-stored-value trap: once a value is edited in a scene it's stored in the .tscn and overrides any later change to the script's default. Changed a default and it "doesn't work"? Check the scene file.
• WeaponSlots are static scene structure — never added/removed at runtime. The build-once caches in Boat._ready() depend on this.
• Scripts aren't @tool, so export setters don't run in the editor — never trust an exported value to have been validated at edit time.

---

Notes / discrepancies found while verifying (2026-07): %Muzzle is a hard requirement of weapon.gd (plain @onready %Muzzle), unlike %Yaw / %Pitch / %Hitbox which use get_node_or_null. A weapon scene isn't truly optional for a def — can_mount() requires weapon_scene != null, so "make a new scene" is what's optional; the def always points at one. CLAUDE.md's layer table lists only 1–5; project.godot also names 6 water and 7 subsystems (the Hitbox layer value 64 in mark12.tscn = layer 7).