Files: asset://, user:// and error handling

Separate project resources from writable user data.

1.0.0

Two virtual roots

Path	Purpose
asset://	Project root beside project.reckfell; game resources
user://	Application data directory; notes, settings and saves

Do not rely on writing to asset:// after export: assets may be packed. Use ResourceLoader for engine resources and FileAccess for ordinary text. Accessing an original PNG in the editor does not prove that the same raw file is included in an export.

Write and read a short note

TextNoteStore.cs

C#
using System.Text;
using Reckfell;

public static class TextNoteStore
{
    public const string Path = "user://script-tools-note.txt";
    public const int MaximumBytes = 4096;

    public static bool TryWrite(string text, out Error error)
    {
        error = Error.InvalidParameter;
        if (Encoding.UTF8.GetByteCount(text) > MaximumBytes) return false;
        using var file = FileAccess.Open(Path, FileAccess.ModeFlags.Write);
        if (file is null)
        {
            error = FileAccess.GetOpenError();
            return false;
        }
        if (!file.StoreString(text))
        {
            error = file.GetError();
            return false;
        }
        file.Flush();
        error = file.GetError();
        return error == Error.Ok;
    }

    public static bool TryRead(out string text, out Error error)
    {
        text = "";
        using var file = FileAccess.Open(Path, FileAccess.ModeFlags.Read);
        if (file is null)
        {
            error = FileAccess.GetOpenError();
            return false;
        }
        if (file.GetLength() > MaximumBytes)
        {
            error = Error.InvalidData;
            return false;
        }
        string candidate = file.GetAsText();
        error = file.GetError();
        if (error != Error.Ok && error != Error.FileEof) return false;
        text = candidate;
        error = Error.Ok;
        return true;
    }
}

The fixed path is user://script-tools-note.txt. The 4096 limit counts UTF-8 bytes rather than characters. Oversized text is refused before opening for writing, preserving the previous note. TryRead checks length before reading.

If Open returns null, immediately get GetOpenError. Write mode replaces contents; this is a simple text example rather than an atomic progress-save system. Use a separate save schema for that.

System paths and asset moves

ProjectSettings.GlobalizePath expands asset:// and user:// into system paths, for example for external tools. LocalizePath converts paths inside the project to asset://; it is not a universal inverse for the user:// directory.

Authored .rscene, .rprefab, .rdata and associated UID sidecars are source data. .reckfell is generated cache. Saying the engine uses no metadata is incorrect: preserve UID and import information when moving assets.

Run the example · Project layout

Reckfell Engine documentationBack to top ↑