Cairn

    Debugging

    The console

    The Console panel shows everything the engine and your scripts log. Warnings are yellow and errors red. The buttons hide and show each level, and the filter box keeps only lines with that text.

    From a script:

    Lua
    TypeScript
    Log.Info("Player at", self.Entity.Position)
Log.Warn("No target set")
Log.Error("This should not happen")
print("the same as Log.Info")

    Script errors

    A script error is logged with its file and line:

    Script error: Assets/Scripts/Player.lua:24: attempt to index a nil value (field 'Target')

    Double-click the line in the console to open that script in your code editor.

    An error in OnUpdate or OnFixedUpdate switches that script off on that entity until the scene restarts, so it is logged once and not sixty times a second. Fix the file and save it: in play mode the script is reloaded and gets another chance.

    Common ones:

    MessageUsual cause
    attempt to index a nil valueA field that was never set, or Scene.FindByName found nothing. Use Scene.Find, which says which name is missing
    the entity no longer existsAn entity kept in self was destroyed. Check entity:IsValid()
    an entity has no 'X'A typo in a component or property name
    the component was removed from the entityA component kept in self is gone

    Seeing what a script is doing

    Draw it. Debug lines show in the viewport while the game plays:

    Lua
    TypeScript
    Debug.Ray(origin, direction * 10, Color.Red)
Debug.Sphere(self.Entity.WorldPosition, self.Range, Color.Yellow)

    Each lasts one frame, so call it from OnUpdate.

    Seeing physics

    Turn on Colliders in the viewport toolbar. Every collider, character and joint is outlined: green is static, orange dynamic, blue kinematic, yellow a trigger, cyan a character and magenta a joint.

    If something falls through the floor, look here first. The usual reasons are a missing collider, or two layers set to pass through each other in Project Settings.

    Pausing and stepping

    In play mode, Pause freezes the game and Step runs one frame. Turn off Game camera to fly around the paused game and select things. The inspector shows their values as they are right now.

    Looking inside a running game

    With the editor started with --server, the lua.run command runs any Lua in the running game:

    ./build/Cairn-CLI/Cairn-CLI '{"command": "lua.run", "code": "print(Scene.Find(\"Player\").Position)"}'

    Log files

    ProgramLog file
    EditorCairn-Editor.log, in the folder it was started from
    Runtime, with a project fileCairn-Runtime.log, in the folder it was started from
    An exported gameGame.log, in the game's folder in the user's data directory

    Crashes

    If the engine itself crashes, the reason and a stack trace are written to the console and to the end of the log file. Read the end of the log first.

    A crash is a bug in the engine, not in your script: a script error can never crash it. Please report it with that part of the log.

    Slow frames

    Press F3 for the Performance window, which shows where each frame's time goes on the CPU and on the GPU.

    Validation

    Start the editor or the runtime with --validation to turn on Vulkan's own checks. It is slower, and reports rendering mistakes as errors in the log.