godot-genre-shooter

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-genre-shooter

Build TPS/hybrid shooters with soft-lock aim, cover, and SpringArm camera.

  • Solves third-person shooter design with aim assist and cover mechanics.
  • Depends on Godot 4.7+ and SpringArm3D for camera and raycasts.
  • Routes FPS-specific tasks to sibling skill for viewmodel and hitscan.
  • Delivers expert patterns via SKILL.md for immediate implementation.

SKILL.md

.github/skills/godot-genre-shooterView on GitHub ↗
---
name: godot-genre-shooter
description: "Expert blueprint for TPS/hybrid shooters: soft-lock aim assist, cover validation rays, SpringArm TPS camera, and genre routing to FPS sibling for viewmodel/hitscan feel. Use for third-person/cover shooters and hybrids. Keywords: TPS, soft_lock, cover, SpringArm3D, hybrid shooter, aim assist — not FPS-only movement."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Genre: Shooter (TPS / Hybrid)

**Ownership:** third-person, hybrid, and shared genre routing (cover, soft-lock, spring-arm camera).  
**Not owned here:** FPS movement, viewmodel bob, FPS camera look, FPS-only hitscan/recoil dumps — use [godot-genre-shooter-fps](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-shooter-fps/SKILL.md).

## 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](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-shooter-fps/SKILL.md) |

### 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](https://docs.godotengine.org/en/stable/tutorials/physics/ray-casting.html) — `PhysicsDirectSpaceState3D.intersect_ray` hitscan queries, exceptions, and collision masks for frame-rate-independent fire.
- [Physics introduction](https://docs.godotengine.org/en/stable/tutorials/physics/physics_introduction.html) — layers/masks, `_physics_process` timing, and body types that keep hit registration deterministic.
- [PhysicsDirectSpaceState3D](https://docs.godotengine.org/en/stable/classes/class_physicsdirectspacestate3d.html) — direct `intersect_ray` / `intersect_shape` for high-frequency shots without RayCast3D node overhead.
- [PhysicsRayQueryParameters3D](https://docs.godotengine.org/en/stable/classes/class_physicsrayqueryparameters3d.html) — from/to, exclude RIDs, and collision_mask for shooter-owned hitscan queries.
- [CharacterBody3D](https://docs.godotengine.org/en/stable/classes/class_characterbody3d.html) — `move_and_collide` projectile bodies with gravity, bounce, and lifetime.
- [SpringArm](https://docs.godotengine.org/en/stable/tutorials/3d/spring_arm.html) — collision-aware TPS camera boom and shoulder offset without clipping into cover.
- [Using decals](https://docs.godotengine.org/en/stable/tutorials/3d/using_decals.html) — perspective-correct bullet holes and impact marks instead of Sprite3D billboards.
- [Controllers, gamepads, and joysticks](https://docs.godotengine.org/en/stable/tutorials/inputs/controllers_gamepads_joysticks.html) — stick look input that aim-assist friction/magnetism modulates.
- [High-level multiplayer](https://docs.godotengine.org/en/stable/tutorials/networking/high_level_multiplayer.html) — RPC authority and unreliable modes for fire events with server-validated hits.
- [Camera3D](https://docs.godotengine.org/en/stable/classes/class_camera3d.html) — FOV punch, aim rays from `-global_basis.z`, and `h_offset` for TPS shoulder swap.
- [PhysicsShapeQueryParameters3D](https://docs.godotengine.org/en/stable/classes/class_physicsshapequeryparameters3d.html) — sphere/shape queries for rocket/grenade AoE without Area3D spam.
- [AudioStreamPlayer3D](https://docs.godotengine.org/en/stable/classes/class_audiostreamplayer3d.html) — layered shot/mechanical/tail players for punchy spatial gunfire.

### Related Skills

#### Prerequisites
- [godot-physics-3d](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-physics-3d/SKILL.md) — CharacterBody3D/RigidBody3D, collision layers, and direct space queries that hitscan and projectiles depend on.
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — look/fire/reload action maps and gamepad stick curves before aim assist and recoil kick.
- [godot-camera-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-camera-systems/SKILL.md) — FPS/TPS camera rigs, FOV, and SpringArm patterns that weapon kick and soft-lock rotate.
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Resource-based WeaponData, scene structure, and import defaults before balancing archetypes.

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

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — simulate TTK, spray patterns, and weapon asymmetry matrices so archetype damage/recoil stay competitive.
- [godot-genre-shooter-fps](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-shooter-fps/SKILL.md) — FPS-specialized movement and viewmodel polish that builds on this genre gunplay lattice.
- [godot-genre-battle-royale](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-battle-royale/SKILL.md) — large-scale matches that reuse hitscan/projectile combat inside drop/zone loops.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — library router and mirrored module entry for cross-skill discovery.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.