Project settings: read, apply and save — documentation

ProjectSettings stores project configuration loaded from project.reckfell. Its values can differ from the state of the running game. Keep player preferences and saved progress separate: see saving data.

Find and change a setting

Open Project → Project Settings → General. Search with Filter Settings; enable Advanced Settings if the setting is absent from the basic list. A full C# key looks like application/run/max_fps: interface labels may be localized, but the programmatic key must remain unchanged.

Editor changes are saved to project.reckfell. Do not edit that file concurrently from the editor and an external tool: one save can overwrite the other. Verify startup settings with a fresh project run, rather than checking only the inspector value.

Read a custom setting safely

Define a game value in project.reckfell:

Configuration
[game]
starting_lives=3

Its full code key is game/starting_lives. Save this helper as ProjectOptions.cs in a Reckfell 1.0.0 C# project:

C#
using Reckfell;
using System;

public static class ProjectOptions
{
    public static int StartingLives
    {
        get
        {
            Variant value = ProjectSettings.GetSetting("game/starting_lives", 3);
            return value.VariantType == Variant.Type.Int
                ? (int)Math.Clamp(value.AsInt64(), 1, 99)
                : 3;
        }
    }

    public static void ApplyFpsLimit(int fps) => Engine.MaxFps = Math.Max(0, fps);
}

ProjectOptions.StartingLives returns the life count. A missing key or a string instead of an integer yields 3. Integers are clamped to 1–99 before conversion to C# int, including values outside the Int32 range.

GetSetting(name, defaultValue) neither creates a missing key nor repairs its type. Use HasSetting to test existence. Use GetSettingWithOverride for active feature tags, as shown in the feature tags guide.

Configuration versus running state

ProjectSettings.SetSetting("application/run/max_fps", 144) changes the configuration record. In the checked process, the live Engine.MaxFps remained unchanged. To change the limit during gameplay, call ProjectOptions.ApplyFpsLimit(60) and read the state from Engine.MaxFps.

The helper treats zero and negative values as unlimited. This does not promise a frame rate: V-Sync, performance and other limits still apply. Changing Engine.MaxFps does not rewrite the value in ProjectSettings.

Do not generalize one setting's behavior to every setting. Many are applied only at startup; others have a dedicated runtime API. Read the specific parameter description and verify actual game behavior.

Save from code

Action	Effect
`SetSetting(name, value)`	Changes memory in this process. Does not write a file itself.
`SetSetting(name, default)`	Removes the key: here `default` is a `Variant` Nil. It does not restore the initial value.
`SetInitialValue(name, value)`	Sets an existing setting's initial value without replacing its current value. Values equal to their initial value are omitted when saving.
`Save()`	Saves configuration to `project.reckfell`. Intended for editor tools, rather than an ordinary player preferences menu.
`SaveCustom(path)`	Saves configuration at the supplied path and returns an `Error`. It is not restricted to your single custom key.

SaveCustom accepts .reckfell or override.cfg endings for text and .binary for binary output. It does not support an arbitrary .json file. Check success against Error.Ok. Writing another file does not automatically reload it into this process.

For player preferences, use a separate ConfigFile under user:// to avoid rewriting the entire project configuration. The check uses asset:// in an isolated test project; do not assume it is writable in an exported game.

Diagnose problems

The value changed but the game did not: use the corresponding runtime API or restart the project.
A change disappears on restart: only memory changed; check the save path and error code.
A setting was omitted from the file: check its initial value; equal values are omitted.
A read has the wrong type: inspect the Variant; do not rely on string-to-number conversion.

Verified in the installed engine: the helper, absent and mistyped keys, integer limits, Nil deletion, setting record versus live FPS, and a separate text save parsed back through ConfigFile. Editor mouse actions, every setting's application, automatic override.cfg loading, export and restart restoration were not separately checked.