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 — controller/hybrid assist & sticky aim
2. cover_validator_rays.gd — cover / peek validity rays
3. tps_camera_spring_arm.gd — SpringArm3D TPS camera collision

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

Decision trees

Camera / stance

Need	Action
Over-shoulder TPS	tps_camera_spring_arm.gd
Cover check before peek-fire	cover_validator_rays.gd
Soft-lock / assist	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 / patterns script
Explosion radius	ShapeCast3D pattern in 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 + advanced-meta-systems.md
Learnable spray	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 + shape AoE

Gunplay theory → tps-gunplay-core.md. Net rewind → 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. 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.