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.