tactical-shooter/docs/mapmaking/06-faq-and-troubleshooting.md

FAQ & Troubleshooting

Common questions, issues, and solutions encountered while building maps.

Template Project

Q: Can I use the template project without the main game repo?

Yes. The template project at client/map_template/ is a standalone Godot project. Copy it anywhere, open it in Godot, and start building. You only need the main repo for packaging (pack_map.gd) and the registry server (map_registry_server.py).

Q: Why does Godot say "Import" instead of "Open"?

The template has its own project.godot, making it a separate project. Use Import to add it to your Godot project list. You're not opening a scene within an existing project.

Q: How do I add the main game's assets to my map?

The template uses placeholder materials. For final maps:

1. Copy your map's .tscn into the main project under client/maps/<name>/
2. Open it from the main project's scenes tab
3. The main game's modular kit and PBR materials will be available
4. Assign materials to your CSG/MeshInstance3D nodes from the main project's asset library

Q: Can I use external models from Blender/Maya?

Yes. Export as .glb or .obj and import into Godot. Keep triangle counts within budget (≤ 50K total, ≤ 5K per mesh recommended). Place imported meshes as children of the map scene root.

Geometry & CSG

Q: My map has light leaks at the corners

Thin gaps between CSG blocks let light bleed through. Fix by overlapping CSG edges by 0.1 units instead of butting them flush.

Bad:  Wall ends at x=10.0, floor ends at x=10.0  →  gap
Good: Wall extends to x=10.1, floor ends at x=10.0 →  overlap

Q: Players can walk through walls

Make sure use_collision = true is set on all CSG geometry nodes. CSG nodes don't have collision by default — you must enable it.

Q: My map renders as a grey box / no materials

Placeholder materials are normal during construction. For the final look, you need to:

1. Copy the map to the main project (see above)
2. Assign materials from the game's asset library
3. Re-bake LightmapGI after materials are assigned

Q: CSG performance is bad in the editor

This is normal. CSG is re-calculated every time you move a node. For testing, convert stable geometry to MeshInstance3D:

• Right-click CSG parent → Convert CSG to Mesh
• Keep a backup copy of the CSG hierarchy in another scene

Q: How do I make a skybox?

Add a WorldEnvironment node and assign an Environment resource:

1. Set Background mode to Sky
2. Create a new Sky resource
3. Assign a PanoramaSky or ProceduralSky material
4. The sky appears behind your geometry

Q: My map has no collision after CSG → Mesh conversion

When you convert CSG to MeshInstance3D, collision is not preserved. Add a CollisionShape3D as a child of each MeshInstance3D, or use Godot's Mesh → Create Trimesh Collision (right-click the MeshInstance3D).

Lighting

Q: My lightmap bake takes forever

Baking time depends on:

• texel_scale — lower = higher resolution = longer bake (try 2.0 for testing)
• bounces — fewer bounces = faster bake (use 1 for quick tests, 3 for final)
• Map size — larger maps bake longer
• Light count — more lights = more calculations

For quick iteration, use Low quality (0) during development and High quality (2) for the final bake.

Q: Baked lighting is too dark

• Increase bounces to 3 (more light bounce = brighter interiors)
• Add a low-intensity ambient fill (OmniLight3D with Static bake mode)
• Lower the texel_scale for more lightmap resolution
• Check that the DirectionalLight3D intensity is sufficient

Q: Lightmap has visible seams

Seams appear where lightmap texels don't align. Fixes:

• Lower texel_scale to 1.0 (higher resolution lightmaps)
• Ensure CSG edges overlap (no gaps)
• Convert CSG to MeshInstance3D before final bake

Q: Shadows look blocky or jagged

This is Godot's shadow mapping at default resolution. For competitive clarity:

• Keep shadow_bias at 0.1 (higher = softer shadows, fewer artefacts)
• Directional shadow max_distance at 20–30 (shadows beyond this use lower resolution)

Q: I see a sphere artifact on my ReflectionProbe

The ReflectionProbe has a probe_mode property — if set to Reflection Probe (sphere mode), it renders as a visible sphere in reflections. Change to Box Probe for interior spaces, or disable reflection visibility via the visible property on the probe's MeshInstance3D child (Godot 4.x).

Q: Can I have a day/night cycle?

No. LightmapGI bakes lighting statically. Dynamic lighting is limited to ≤ 4 real-time lights. Day/night cycles are outside the current scope.

Validation

Q: The validator says "No MeshInstance3D nodes found"

Your map is using CSG nodes that haven't been converted to meshes. The validator counts mesh triangles — CSG nodes are scanned as MeshInstance3D after conversion. Either:

1. Convert CSG → Mesh for the area you want validated (right-click → Convert CSG to Mesh)
2. This warning is expected during early construction stages

Q: The validator fails with "Scene cannot be instantiated"

The scene depends on resources that don't exist in the template project. This usually happens when the map references game assets from the main project. Either:

1. Run the validator from the main game project (--path client with the main client/project.godot), or
2. Strip external dependencies — the map should be self-contained

Q: The validator reports texture errors but my textures are 1024×1024

Check for textures with different aspect ratios. A 2048×512 texture fails because the larger dimension (2048) exceeds 1024. Resize or tile.

Q: Can I skip certain validator checks?

Not directly. Run the validator, fix errors, then fix warnings. If a check produces a false positive, the @tool scripts are in client/tools/validate_map/ — you can edit the constants (e.g. MAX_TOTAL_TRIANGLES) for custom pipelines.

Packaging

Q: The .pck file is very large

The .pck includes all dependencies of the scene. Large files mean:

• High-resolution textures (use ≤ 1024×1024 per the budget)
• High-poly meshes (stay under 50K triangles)
• Embedded audio or other large assets

Run the validator first to check budgets.

Q: I get "Failed to load pack" in-game

Possible causes:

• .pck file is corrupted (check SHA-256 checksum)
• The map scene or a dependency path changed between packaging and loading
• The .pck was built with a different Godot version than the game
• The resource path in the .pck conflicts with a path in the base game

Solution: Re-package the map from the same Godot version the game uses. Verify with curl that the download matches the server's checksum.

Q: Can I update a map without changing the client version?

Yes. The .pck is additive content. Update the .pck on the registry server and increment the version field in the .json metadata. The client will re-download when it notices the version mismatch.

Q: Can I host the registry server on a different port?

Yes. Use --port <port> or the MAP_REGISTRY_PORT environment variable. The client's MapDownloader has a registry_url property you can set.

Q: Can I load more than one .pck at a time?

Yes. ProjectSettings.load_resource_pack() is additive. Multiple .pck files can be loaded simultaneously — each adds its resources to the global namespace.

Q: The registry server returns 404 for my map

• Check that the .pck file is in the maps directory (default ./packed_maps/)
• Check the file extension is .pck (lowercase)
• The server auto-scans every 5 seconds — wait or send SIGHUP to force a scan
• Verify by listing: curl http://localhost:8090/maps

General

Q: Can I make a hostage rescue map?

The SDK is gameplay-agnostic. The groups ct_spawn, t_spawn, bomb_site, and buy_zone are the default set. You can add your own groups (e.g., hostage, hostage_zone) — the game logic discovers them at runtime. Check the game's plugin API documentation for custom group support.

Q: Can I use this SDK for a different game?

The SDK is designed for Tactical Shooter's Godot project structure. The packaging and validation scripts are reusable for any Godot map-authoring workflow, but the group conventions and gameplay nodes are game-specific.

Q: The editor validator doesn't run

The template_map.gd script uses @tool and checks Engine.is_editor_hint(). Make sure:

1. The script is attached to the root node of the scene
2. You're editing the scene in the Godot editor (not running the game)
3. The Output panel is visible (Window → Output)

Q: How do I report a bug in the SDK?

Open an issue on the project's Gitea repository. Include:

• SDK version (commit hash)
• Godot version
• Steps to reproduce
• Log output (editor or CLI validator)

Q: Can I contribute validator modules?

Yes. See Validation — Adding a Custom Validator Module. Submit a pull request with your module and updated documentation.