MANUAL / Extend the editor / Importers and asset types

Importers and asset types

Teach the editor new file formats: importers turn a source file into something the engine reads, asset types give your own files a place in the Content panel.

Capabilitiesimporters, exporters, asset-types

Permissionassets.write

SamplesImporter, AssetType

Importers

Host.AddImporter(new ImporterOptions(id, name, extensions, outputExtension), run) adds a format to File › Import. run gets a FileJob on a worker thread: read SourcePath, write OutputPath in a format the engine imports (for example .obj for a mesh), report progress, warnings and errors, and stop early when IsCancelled turns true.

Exporters are the same in reverse: Host.AddExporter adds File › Export with Plugin.

PointCloudImporter.cs

public sealed class PointCloudImporter : EditorPlugin
{
    public override void OnLoad() =>
        // File > Import offers .xyz files; the plugin writes an .obj the engine imports as a mesh.
        Host.AddImporter(new ImporterOptions("PointCloud", "Point cloud (.xyz)", ".xyz", ".obj"), Import);

    // Runs on a worker thread.
    private static void Import(FileJob job)
    {
        var obj = new StringBuilder();
        string[] lines = File.ReadAllLines(job.SourcePath);
        for (int index = 0; index < lines.Length; ++index)
        {
            string[] values = lines[index].Split(' ', StringSplitOptions.RemoveEmptyEntries);
            if (values.Length < 3)
            {
                job.Warning($"Line {index + 1} skipped: needs x y z.");
                continue;
            }
            obj.AppendLine($"v {values[0]} {values[1]} {values[2]}");
            job.SetProgress((index + 1) / (float)lines.Length);
            if (job.IsCancelled) return;
        }
        File.WriteAllText(job.OutputPath, obj.ToString());
    }
}

Asset types

Host.AddAssetType(options, handlers) registers a file extension. Files of that type show in the Content panel with your icon and a one-line summary; New creates one; a double click opens it through your plugin; edited assets marked with Host.MarkAssetDirty are saved with the project.

Handler	Called when
`CreateDefault`	The user creates a new asset: return its first bytes
`Load`	The editor lists the file: validate it and return a summary (or reject it)
`Open`	The user double-clicks it
`Save`	The project saves an asset you marked dirty: return its bytes

ChecklistAssetType.cs

public sealed class ChecklistAssetType : EditorPlugin
{
    public override void OnLoad()
    {
        // Capability "asset-types": .kchecklist files in the Content Browser, with New and Open.
        Host.AddAssetType(new AssetTypeOptions("Checklist", "Checklist", ".kchecklist") { Icon = "list-checks" }, new AssetTypeHandlers
        {
            CreateDefault = () => Encoding.UTF8.GetBytes("[ ] First item\n"),
            Load = (path, bytes) =>
            {
                string[] items = Encoding.UTF8.GetString(bytes).Split('\n', StringSplitOptions.RemoveEmptyEntries);
                int done = items.Count(item => item.StartsWith("[x]"));
                return new AssetLoadResult(true, $"{done} of {items.Length} done");
            },
            Open = path => Host.Notify(Severity.Info, "Checklist", Path.GetFileName(path)),
        });
    }
}

Bring files in from code

Host.ImportFile(source, folder) imports a file into the project as if the user had used File › Import; Host.CreateAssetFile(folder, name, bytes) writes a new asset; Host.ReadContentFile(path) reads one. Writing needs permission assets.write.

KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.