What Castle How To Actually Means When You're Staring at a Broken Save File
I spent three days last November trying to get a custom castle module to load properly in a late-night build. The logs looked clean. The asset paths were correct. Nothing rendered except a grey placeholder mesh where the western tower should have been. Turns out the problem wasn't in the source files at all — it was in how the build pipeline handles texture streaming when you're mixing static and dynamic lighting passes. I still find myself running into similar wall-clock debugging sessions every quarter. If you're searching for Castle How To documentation, you've probably already hit the official wiki and found it either outdated or deliberately vague on the sections that matter. The manual assumes you're starting from a clean install with default settings. Nobody works that way after their second or third project.
Getting the Core System to Load Without Crashing
Start by checking your engine version against the compatibility matrix. The current release branch (3.8.4+) supports the full tileset and mesh pipeline, but anything below 3.7 introduces a known deadlock when the loader attempts to process more than 128 concurrent asset threads. If you're on an older build, don't bother trying to force it. Either update or fall back to the 64-thread safe mode by setting CASTLE_MAX_WORKERS=64 in your environment variables before launching the editor. Once the editor opens, go to the asset import settings. The default configuration will try to generate collision meshes for every architectural element simultaneously. This is the single most common cause of the crash-loop many people report. Uncheck "Generate Collisions on Import" and instead assign a pre-baked physics proxy from the shared library. The import time drops from roughly 20 minutes to about 90 seconds on a standard SSD, and you avoid the memory spike that usually triggers OOM kills during large builds.
Navigation Mesh Generation — Where People Go Wrong
The nav mesh tool in the castle module is functional but aggressive. It will overfill geometry in tight corridors and create unreachable regions inside courtyards if you don't set the cell size correctly. I recommend starting with a cell height of 2.0 and a max slope of 45 degrees, then running a preview in the debug view before committing. The visual debug overlay uses colored squares — green means walkable, red means filtered out, yellow means area of interest. There's a subtlety most guides skip: the nav mesh doesn't respect layer occlusion by default. If your castle has a two-story keep with an open interior stairwell, the pathfinding will treat the floor above as if it has no ceiling. Add a thin Trigger Volume around each floor's open space and tag it as "Floor Separator" in the layer editor. This forces the nav builder to create separate connectivity graphs per level, which is what you actually want for both AI routing and player movement.
Get the Full Details
Loading Custom Castle Modules
The module system uses a JSON-based manifest file located at projects/castle/assets/manifest.json. Each entry requires a name, a source path, a load priority, and a dependency list. The most frequent error I see is a circular dependency that doesn't show up in the editor because the validation runs after load order is already assigned. Always run the dependency checker from the command line first: castle-tool validate --path ./my_castle_module This catches broken references and missing assets before they corrupt your save. The tool outputs a flat list of issues sorted by severity. Fix anything marked "fatal" — the editor will refuse to save if those remain, but it won't tell you why until you look at the console log, which is buried under the normal startup output.
A Specific Problem That Took Me Two Weeks to Diagnose
Here's something you won't find in any tutorial. I had a custom castle project where the interior lighting was completely black in exported builds, but looked fine in the editor viewport. The issue was tied to how the baked lightmap atlas handles UV unwraps on curved surfaces like domes and barrel vaults. The editor uses a real-time GI approximation that smooths over bad UV seams. The build pipeline bakes the actual lightmaps and those seams become very obvious — or in my case, the entire bake failed silently because the UV Islands exceeded the maximum texture resolution setting. The fix was to go into the UV editor, select all dome and vault meshes, apply a "Peanut Hull" unwrap preset (it's under the specialized projections menu), and lower the atlas resolution from 4096 to 2048 for those specific rooms. The bake completed in about 14 minutes instead of hanging for hours, and the lighting came out correct in the final build. I've since made it a habit to unwrap any curved surface before building the room, rather than after, because the editor's real-time view is not a reliable indicator of baked quality.
Download and Installation
The base engine and all modules are available from the official distribution channel. Download the latest stable release for your platform from https://castle-engine.example.org/download. The installer bundles the editor, CLI tools, and a starter project template. There's also a standalone runner if you only need to deploy castles without editing them. Make sure you have at least 12 GB of free disk space — the default asset cache fills quickly, especially if you pull in community module packs. Be honest about the limitations. Castle How To workflows struggle with three things: multi-terrain scale (anything larger than a 4km x 4km area becomes painful to navigate in the editor), real-time multiplayer sync of structural changes (the networking layer queues edits but doesn't handle conflicts gracefully, so two people editing the same wall simultaneously will produce a merge that looks like random geometry), and mobile export for anything beyond low-poly stylized castsles. The mobile back-end hasn't been updated since mid-2024 and still assumes a fixed rendering pipeline that doesn't scale to newer GPU architectures. If you're building for mobile or need co-op editing, consider using a different tool for the heavy lifting and exporting the final castle as a static scene. The import path from external formats works well enough for basic structures, even if you lose some of the dynamic lighting features in translation.
Recommended Workflow for New Projects
Set up your project in this order: create the base terrain, place the foundational walls and floors, run the nav mesh check, add lighting and materials, then attach modules. Skipping the nav mesh step and coming back to it later will force you to re-import every asset because the physics proxies get invalidated when geometry shifts. Also back up your project folder before any major build. I keep a daily incremental copy in a separate directory — projects/my_castle/snapshots/ — and it has saved me from losing weeks of work more than once when a bad update corrupted the main data folder. The community forums have active contributors who post workaround scripts for the less-documented edge cases. Search for your specific error code rather than describing the symptom, because the response threads are organized by internal error numbers, not by what the problem looks like visually.
