godot-genre-shooter

Core Loop

Engage → Aim (soft-lock/cover) → Fire → Confirm → Acquire Next

NEVER Do (TPS / hybrid)

• NEVER put FPS viewmodel/bob/look recipes in this skill — route to shooter-fps.
• NEVER use _process() for hit registration — _physics_process + space-state queries.
• NEVER trust the client for authoritative hits — server validate / rewind.
• NEVER use Area3D overlap for bullets — ray / shape queries.
• NEVER hardcode weapon stats in logic — WeaponData Resources.
• NEVER skip excluding the shooter's RID on queries.
• NEVER use TCP for shooter net sync — ENet/UDP.

MANDATORY scripts (non-FPS paths)

> Read before implementing the matching system:

1. [soft_lock_aim_assist.gd](scripts/soft_lock_aim_assist.gd) — controller/hybrid assist & sticky aim
2. [cover_validator_rays.gd](scripts/cover_validator_rays.gd) — cover / peek validity rays
3. [tps_camera_spring_arm.gd](scripts/tps_camera_spring_arm.gd) — SpringArm3D TPS camera collision

Also available: [advanced_weapon_controller.gd](scripts/advanced_weapon_controller.gd) (shared weapon controller — prefer FPS skill for FPS feel), [shooter_patterns.gd](scripts/shooter_patterns.gd), [projectile.gd](scripts/projectile.gd), [weapon_recoil_pattern.gd](scripts/weapon_recoil_pattern.gd) (spray Resource), [lag_compensator.gd](scripts/lag_compensator.gd) (server rewind).

Decision trees

Camera / stance

| Need | Action |

|---|---|

| Over-shoulder TPS | [tps_camera_spring_arm.gd](scripts/tps_camera_spring_arm.gd) |

| Cover check before peek-fire | [cover_validator_rays.gd](scripts/cover_validator_rays.gd) |

| Soft-lock / assist | [soft_lock_aim_assist.gd](scripts/soft_lock_aim_assist.gd) |

| True FPS digsite | → godot-genre-shooter-fps |

Fire mode

| Need | Action |

|---|---|

| Hitscan / projectile theory | Shared WeaponData + space-state; FPS implementation details in shooter-fps |

| Pooled projectiles | [projectile.gd](scripts/projectile.gd) / patterns script |

| Explosion radius | ShapeCast3D pattern in [shooter_patterns.gd](scripts/shooter_patterns.gd) |

Net

| Need | Action |

|---|---|

| Client juice | Predict tracers locally |

| Damage | Server authoritative; show no-reg on mismatch |

| Net rewind / lag comp | [lag_compensator.gd](scripts/lag_compensator.gd) + [advanced-meta-systems.md](references/advanced-meta-systems.md) |

| Learnable spray | [weapon_recoil_pattern.gd](scripts/weapon_recoil_pattern.gd) |

Weapon selection (short)

Hitscan for rifles/SMGs; physical projectiles for rockets/arrows; balance in WeaponData Resources (.tres), never hardcoded on nodes.

| Archetype | ROF | Damage | Implementation |

|-----------|-----|--------|----------------|

| SMG | High | Low | Hitscan + tight vertical spray |

| Sniper | Low | High | Hitscan + tracer |

| Shotgun | Burst | Medium | Multi-pellet spread, <10m |

| Rocket | Slow | High | [projectile.gd](scripts/projectile.gd) + shape AoE |

Gunplay theory → [tps-gunplay-core.md](references/tps-gunplay-core.md). Net rewind → [advanced-meta-systems.md](references/advanced-meta-systems.md).

Recoil and feel (WHY)

Apply kick to camera rotation and spread bloom, not weapon mesh alone. Learnable spray via [weapon_recoil_pattern.gd](scripts/weapon_recoil_pattern.gd). Layer gunfire: mechanical + shot + reverb tail on separate 3D players.

Multiplayer (short)

Client predicts VFX/tracers; server validates hits (rpc + rewind). Never trust client damage. ENet/UDP, not TCP. Server wins on mismatch — show no-reg feedback.

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Ray-casting — PhysicsDirectSpaceState3D.intersect_ray hitscan queries, exceptions, and collision masks for frame-rate-independent fire.
• Physics introduction — layers/masks, _physics_process timing, and body types that keep hit registration deterministic.
• PhysicsDirectSpaceState3D — direct intersect_ray / intersect_shape for high-frequency shots without RayCast3D node overhead.
• PhysicsRayQueryParameters3D — from/to, exclude RIDs, and collision_mask for shooter-owned hitscan queries.
• CharacterBody3D — move_and_collide projectile bodies with gravity, bounce, and lifetime.
• SpringArm — collision-aware TPS camera boom and shoulder offset without clipping into cover.
• Using decals — perspective-correct bullet holes and impact marks instead of Sprite3D billboards.
• Controllers, gamepads, and joysticks — stick look input that aim-assist friction/magnetism modulates.
• High-level multiplayer — RPC authority and unreliable modes for fire events with server-validated hits.
• Camera3D — FOV punch, aim rays from -global_basis.z, and h_offset for TPS shoulder swap.
• PhysicsShapeQueryParameters3D — sphere/shape queries for rocket/grenade AoE without Area3D spam.
• AudioStreamPlayer3D — layered shot/mechanical/tail players for punchy spatial gunfire.

Related Skills

Prerequisites

• godot-physics-3d — CharacterBody3D/RigidBody3D, collision layers, and direct space queries that hitscan and projectiles depend on.
• godot-input-handling — look/fire/reload action maps and gamepad stick curves before aim assist and recoil kick.
• godot-camera-systems — FPS/TPS camera rigs, FOV, and SpringArm patterns that weapon kick and soft-lock rotate.
• godot-project-foundations — Resource-based WeaponData, scene structure, and import defaults before balancing archetypes.

Complements

• godot-combat-system — damage events, hit zones, and health pipelines that consume shooter take_damage results.
• godot-raycasting-queries — reusable ray/shape query helpers for cover checks, LOS, and hitscan without duplicating query setup.
• godot-audio-systems — bus routing and 3D attenuation for mechanical + shot + reverb-tail gunfire layers.
• godot-multiplayer-networking — ENet peers, RPC modes, and authority so fire is predicted client-side and damage is server-validated.
• godot-adapt-single-to-multiplayer — prediction, reconciliation, and lag-compensation shells around hitscan validation.
• godot-particles — muzzle flash, tracers, and impact bursts that sell gunplay without blocking the fire path.

Downstream / consumers

• godot-monte-carlo-balancer — simulate TTK, spray patterns, and weapon asymmetry matrices so archetype damage/recoil stay competitive.
• godot-genre-shooter-fps — FPS-specialized movement and viewmodel polish that builds on this genre gunplay lattice.
• godot-genre-battle-royale — large-scale matches that reuse hitscan/projectile combat inside drop/zone loops.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.