tactical-shooter/client/map_template/README.md

Tactical Shooter — Map Template

A standalone Godot 4 project for building custom competitive maps.

Quick Start

1. Copy this directory — cp -r map_template/ maps/my_custom_map/
2. Rename template_map.tscn — e.g. de_dust2.tscn
3. Open the new directory in Godot 4 — add the map template project
4. Build geometry — use CSG brushes or instance modular kit pieces
5. Place gameplay prefabs — spawn points, bomb sites, buy zones
6. Bake lighting — select LightmapGI → "Bake Lightmap"
7. Package & ship — use the PCK pipeline to publish

Directory Structure

map_template/
├── project.godot           # Standalone Godot project config
├── template_map.tscn       # Demo map scene (copy & rename)
├── template_map.gd         # Editor tool script (auto-validates map)
└── assets/
    └── prefabs/
        ├── ct_spawn.tscn       # Counter-Terrorist spawn point
        ├── t_spawn.tscn        # Terrorist spawn point
        ├── buy_zone.tscn       # Purchase zone area
        ├── bomb_site.tscn      # Bomb plant site area
        ├── cubemap_origin.tscn # Reflection probe origin
        └── map_bounds.tscn     # Out-of-bounds kill wall

Prefab Reference

Node Type Conventions

All gameplay nodes are discovered by Godot groups, not by node name. Add nodes to these groups for game logic to find them:

Group	Node Type	Purpose
ct_spawn	Marker3D	CT team spawn position
t_spawn	Marker3D	Terrorist team spawn position
buy_zone	Area3D	Purchase-eligible zone
bomb_site	Area3D	Bomb plant zone
cubemap_origin	Node3D	Reflection cubemap capture point
map_bounds	Area3D	Out-of-bounds kill wall

Additional groups (informational, set by map author):

• bombsite_a / bombsite_b — sub-identify which bomb site
• ct_buy / t_buy — team-specific buy zones (if separated)

ct_spawn.tscn

• Type: Marker3D (green pad with +Z direction arrow)
• Group: ct_spawn
• Usage: Place on floor, one per player slot (usually 5). The +Z arrow indicates the direction players face on spawn. Add child Node3Ds for additional spawn positions.
• Customisation: Duplicate instances rather than editing the prefab. Adjust position and rotation only — the pad is cosmetic.

t_spawn.tscn

• Type: Marker3D (red pad with +Z direction arrow)
• Group: t_spawn
• Same usage as ct_spawn but for the Terrorist team.

buy_zone.tscn

• Type: Area3D with CollisionShape3D
• Group: buy_zone
• Usage: Place to define an area where players can purchase items. Resize the child CollisionShape3D to match the room. The Area3D monitors body_entered/body_exited to activate/deactivate the buy menu.
• Visual: Semi-transparent yellow box as editor reference.

bomb_site.tscn

• Type: Area3D with CollisionShape3D
• Group: bomb_site
• Usage: Place to define where the bomb can be planted. Resize the CollisionShape3D to cover the site. Rename the instance "BombsiteA" or "BombsiteB" and add the sub-group (bombsite_a / bombsite_b).
• Visual: Semi-transparent orange floor panel + CSG subtraction hint for plantable ground area.

cubemap_origin.tscn

• Type: Node3D with small blue marker
• Group: cubemap_origin
• Usage: Mark the ideal position for the ReflectionProbe cubemap capture. Place at eye height (1.6 units above floor) in the most visually prominent part of the map.
• Note: The ReflectionProbe itself is a separate node — place it at this marker's position after geometry is finalised.

map_bounds.tscn

• Type: Area3D with CollisionShape3D
• Group: map_bounds
• Usage: Invisible kill wall. Place one per perimeter side, resize to form a closed box around the playable area. Detects body_exited to teleport/kill out-of-bounds players.
• Visual: Semi-transparent red wall as editor reference.

Building a Map — Checklist

Essential

• Floor geometry (CSGBox3D or modular kit tiles)
• Wall geometry enclosing the playable area
• Ceiling or skybox boundary
• Collision on all CSG brushes (use_collision = true)

Gameplay

• CT spawn points for each player (group ct_spawn)
• T spawn points for each player (group t_spawn)
• Two bomb sites, each with group bomb_site
• Buy zones at each spawn area (group buy_zone)
• Map bounds perimeter walls (group map_bounds)

Lighting

• WorldEnvironment with sky/ambient
• DirectionalLight3D (sun) with shadows enabled
• Fill/ambient OmniLight3D(s)
• ReflectionProbe at cubemap origin
• LightmapGI configured with quality=2, bounces=3
• Lightmap baked (select LightmapGI → "Bake Lightmap")

Validation

• Open template_map.tscn in Godot editor — the tool script auto-runs
• Check Output panel (bottom dock) for validation results
• All checks pass (green ✓)
• For headless validation, use the main project's validator from client/: godot --script scripts/validate_scene.gd -- --scene=res://maps/my_map.tscn

CSG Building Guide

Godot's CSG (Constructive Solid Geometry) nodes let you build map geometry directly in the editor. Key shortcuts:

• W — Move tool
• E — Rotate tool
• R — Scale tool
• Ctrl+D — Duplicate selected node
• Ctrl+Shift+C — Bake LightmapGI

CSG node types used in this template:

• CSGBox3D — Basic wall/floor/ceiling blocks
• CSGCombiner3D — Grouped geometry (container, non-collidable parent)
• CSGSphere3D / CSGCylinder3D — Curved shapes

CSG operations:

Operation	Effect
Union (0)	Adds to existing CSG (default)
Subtraction (1)	Cuts hole through parent CSG
Intersection (2)	Keeps only overlapping volume

Performance rule: Use as few CSG nodes as possible. For detailed maps, bake CSG to a MeshInstance3D via Scene → "Convert CSG to Mesh" when geometry is finalised.

Integrating with the Main Project

When your map is complete:

1. Copy your .tscn + assets into the main project at client/maps/<map_name>/
2. Pack as .pck: cd client && godot --headless --pack --export-pack maps/<map_name>.pck res://maps/<map_name>.tscn
3. Register with master server via POST /api/v1/maps/register
4. Test in-game: connect to server and changelevel <map_name>

Limitations

• Standalone preview: Direct CSG rendering in this template uses basic placeholder materials. Final maps should use the main project's modular kit assets and PBR materials.
• Lightmap baking: Godot 4.7 LightmapGI baking is editor-only. Open this project in the editor to bake.
• Non-Euclidean geometry: Not supported by CSG. Use MeshInstance3D for complex shapes.