Krotox Engine › Docs › Scripting API › Systems & Utilities

Editor tool scripts & built-in scripts

Automating level building with C# editor tools: EditorTool classes, ToolButton methods, authoring scenes and prefabs with EditorScene, placement helpers, progress reporting, running tools headless in CI, and the ready-made scene-loading scripts.

Editor tools

An editor tool is a C# class in your project that shows up in the Editor Tools panel (View ▸ Editor Tools). Its public fields become a form, and each method marked [ToolButton] becomes a button. Use tools for repetitive authoring: building a level campaign, scattering props, generating prefab variants, batch-renaming.

using KrotoxEngine;
using KrotoxEngine.Editor;   // EditorProgress

public class BlockoutTool : EditorTool
{
    public override string DisplayName => "Level Blockout";
    public override string Description => "Scatters props and writes a level.";

    [Header("Scatter")]
    [Range(1, 500)] public int Count = 100;
    public float Radius = 25.0f;
    public Prefab Prop;

    [ToolButton("Build Level")]
    public void Build()
    {
        EditorScene.CreateEmpty();
        EditorPlacement.Scatter(Prop, Vector3.Zero, Radius, Count, minDistance: 1.5f);

        for (int i = 0; i < Count && !EditorProgress.IsCancellationRequested; i++)
            EditorProgress.Report(i + 1, Count, "Placing");

        EditorScene.SaveAs("Levels/Blockout.ktx", overwrite: true);   // relative to Assets
        LogInfo("Done");
    }
}

How tools behave:

Any class deriving from KrotoxEngine.EditorTool appears in the list under its DisplayName.
Public fields are reflected like a script's: numbers, bools, strings, vectors, colours, entity and prefab slots, and arrays. Their values are saved to a <ProjectName>.ktxtools file next to the project, so a tool's setup survives a restart and can be committed.
A tool runs only when you press one of its buttons: never when it is discovered and never on assembly reload.
Tools are created for each run and thrown away afterwards, so keep state in fields (which are saved) rather than in memory between runs.
After a reload, saved field values are matched against the current fields, so renaming a field drops its stored value instead of sending it to the wrong field.

EditorScene

EditorScene only works inside a [ToolButton] run and throws anywhere else.

Member	Meaning
`IsAuthoring`	Whether a tool authoring session is active.
`CreateEmpty()`	Clear the authoring scene.
`CreateEntity(...)`, `CreateGroup(name)`	Make entities and groups.
`Instantiate(prefab, position, ..., unpack)`	Place a prefab, optionally unpacked into plain entities.
`FindEntity`, `FindEntities`, `FindEntityWithTag`, `FindEntitiesWithTag`	Look things up in the authoring scene.
`SaveAs(path, overwrite)`	Save the authoring scene as a `.ktx` under `Assets/`.
`SaveAsPrefab(entity, path, overwrite)`	Save an entity and its children as a `.prefab`, registered with the asset manager.
`CreatePrefabVariant(basePrefab, newPath, configure, overwrite, keepInstanceInScene)`	Instantiate a base prefab, change it in a callback, and save the result as a new prefab.

SaveAs refuses absolute paths, refuses anything outside the project's asset folder, and refuses to overwrite unless you pass overwrite: true.

Placement and helpers

EditorPlacement: Scatter, Grid, Line and Circle placement of prefabs.
EditorProgress: Report(current, total, message) shows a progress bar; check IsCancellationRequested to stop when the user cancels.
Protected helpers on EditorTool: LogInfo, LogWarn, LogError, Lerp, Clamp.

Example: generating prefab variants

public class PrefabGeneratorTool : EditorTool
{
    public override string DisplayName => "Prefab Generator";
    public override string Description => "Makes enemy variants from a base prefab.";

    public Prefab BaseEnemy;

    [ToolButton("Generate Boss Variant")]
    public void GenerateBoss()
    {
        EditorScene.CreatePrefabVariant(
            BaseEnemy,
            "Prefabs/Enemies/Boss.prefab",
            configure: variant =>
            {
                variant.Scale = new Vector3(2.5f, 2.5f, 1.0f);
                var sprite = variant.GetComponent<SpriteRendererComponent>();
                if (sprite != null) sprite.Color = new Vector4(1.0f, 0.2f, 0.2f, 1.0f);
                variant.AddScript<BossAI>();
            },
            overwrite: true);

        LogInfo("Boss.prefab generated");
    }
}

Running a tool from the command line

Tools can run headless, which makes them testable in continuous integration. The first argument is the project file; the process exits with a non-zero code if the tool fails:

KrotoxEngine-Editor.exe MyGame/MyGame.ktxproj --run-tool MyGame.BlockoutTool::Build

Level generation in tools

The KrotoxEngine.PCG library works in tools as well as at run time: generate a layout, bake it with TilemapBaker, place prefabs and save a scene, all from one button. See Tilemap, Grid & level generation API.

Built-in scripts

ScriptCore ships ready-made scripts you can attach without writing code:

Script	Fields	What it does
`KrotoxEngine.SceneLoader`	`TargetScenePath`, `DelaySeconds`, `AutoLoadOnStart`	Loads a scene after a delay, on start, or when `StartLoading()` / `StartLoadingScene(path, delay)` is called. Good for splash screens.
`KrotoxEngine.SceneChangeButton`	`TargetScenePath`	Loads the scene when the entity's UI button is pressed. Ignores the first 0.2 s of Play, so a click that started the game does not skip a menu.
`KrotoxEngine.SceneTransitionTrigger`	`TargetScenePath`, `TargetTag`, `RequireKeyPress`, `InteractKey`	Loads the scene when an entity with `TargetTag` (default `"Player"`) touches it, or on `InteractKey` while touching if `RequireKeyPress` is on. An empty tag lets anything trigger it.

TargetScenePath shows a scene picker in the inspector and stores the path in the form that works in shipped games.