#Troubleshooting

#Building

#CMake cannot find Vulkan or glslc

Install the Vulkan SDK on Windows and macOS, and the Vulkan loader and shaderc packages on Linux. On macOS, run the SDK's setup-env.sh or install its system-wide components, so glslc is on the path.

#The first build takes a long time

It downloads and compiles every dependency, Jolt and Dear ImGui among them. Later builds only compile what changed.

#The build fails at the end with a failing test

The unit tests run as the last build step. The output above the failure names the test and the check. If you changed a Lua binding or an agent command, the generated pages are out of date: run CAIRN_UPDATE_DOCS=1 ./build/Tests/Cairn-Tests.

#Errors on Windows or Linux

Only macOS has been built so far. The platform-specific files (the crash handler, sockets, finding the program's own path) have not been compiled elsewhere.

#Starting

#"Could not create a Vulkan instance" or no GPU found

The machine needs a GPU with Vulkan 1.3. On macOS that is any Apple Silicon or recent Intel Mac, through MoltenVK, which the Vulkan SDK installs.

#The window is black

The scene has no camera with Primary ticked, or the camera is looking away from everything. In the editor, select the camera to see what it sees drawn as lines.

#Everything is very dark

There is no light and no sky, or the scene's Exposure is too low. Deselect everything and look at the render settings in the inspector.

#Projects and scenes

#A project does not open

The log says why. The usual reasons are a start scene that was deleted or moved without its .meta file, and a scene that will not load.

#A scene does not load

A scene with an instance of a prefab that cannot be read does not load at all, so that nothing is half-read. Put the prefab file back, with its .meta file.

#A model draws grey, or a texture white

The material or texture it names is missing. A missing material draws as the default one and a missing texture as white, so that a broken reference still draws. It usually means a file was moved or renamed without its .meta file.

#An asset is not in the Assets panel

Press the refresh button, the two arrows beside New. The panel does not watch the folder for new files. Files in folders whose names start with a dot are never listed.

#An asset got a new ID and everything lost it

Its .meta file was left behind when the file was moved. Move the two together, or use Rename and drag-to-folder in the Assets panel, which do.

#Scripts

#A script does nothing

Look at the console. A script whose update failed is switched off until the scene restarts. Also check that the entity is switched on, and that the file returns its table on the last line.

#self.Entity.Position.y = 5 does nothing

Reading Position gives a copy. Use self.Entity:Move(0, 5, 0) or assign a whole vector.

#A field is nil

A Field.Entity() that was never set in the inspector is nil. An asset field that was never set is an empty handle: check it with handle:IsValid().

#No completion in the code editor

Open the project's folder, not a single file. For Lua, check that the Lua language server is installed. A TypeScript project needs nothing installed in the code editor. The editor writes .luarc.json and .cairn/api.d.lua into a Lua project, or tsconfig.json and .cairn/api.d.ts into a TypeScript one, the first time it opens it. See Code editor setup.

#Physics

#Something falls through the floor

Turn on Colliders in the viewport. Either one of them has no collider, or their two layers are set to pass through each other in Project Settings. A very fast, very small body can also pass through a thin wall.

#A character does not move

Move sets a walking speed, and it is the script's job to call it. Check that the entity has a CharacterController and not also a Rigidbody with colliders, which are not used next to one.

#A collision function is never called

The entity needs a collider, and at least one of the two bodies must be dynamic or a character. Two static bodies never report a contact. For a pickup, tick Is Trigger and use OnTriggerEnter.

#A ray hits the entity it starts from

A ray that starts inside a body hits it at distance zero. Pass the entity as the last argument to ignore it.

#Input and sound

#A key does nothing in the editor

The game has the keyboard only while it is playing and not paused. Click the viewport first.

#An action is always 0

Its name in the script does not match the one in Project Settings, which is case sensitive.

#No sound

Check the bus volumes in Project Settings. A hidden or headless run opens no sound device on purpose.

#Exported games

#macOS says the game is from an unidentified developer

Exported games are not signed or notarized. Right-click the app and choose Open the first time.

#The exported game shows nothing

It was exported from the files on disk. Save the scene before exporting, and check that the project has a start scene.