CVarBase<T>

public abstract partial class CVarBase<T> : Resource, ICVar

Inherits: Resource⿻, ICvar
Namespace: FractalPike.PikeConsole.Core.RuntimeExecution.Cvars.Extensions

Description

Root class for ALL CVars that manages initialization, execution, session persistance, cheat protection, registry indexing and formatting.

It serves both as the entry point for anyone wanting to expand the API with more CVar types, and as a contract to ensure consistent interactions between CVars.

For a tutorial on how to create a custom CVar type, see the cvar guide.

Events

Scope	Delegate	Name
`public`	`Action<T>?`	ValueChanged
`public`	`Action?`	ValueInvalidated

Properties

Scope	Return	Name
`public`	`T`	Value
`public`	`bool`	IsModified
`public`	`string`	FormattedValue
`public`	`bool`	Persist
`public`	`bool`	IsCheat
`public`	`string`	CurrentValueDisplay
`public`	`string`	DefaultValueDisplay
`public`	`string`	Description
`public`	`string`	Signature
`public`	`string`	ShortDesc
`public`	`string`	LongDesc
`public abstract`	`string`	DisplayType
`public virtual`	`string`	Usage
`protected abstract`	`T`	_defaultValue
`protected abstract`	`T`	_value
`protected virtual`	`string`	DescriptionInternal

Methods

Scope	Return	Name
`public`	`void`	Initialize
`protected virtual`	`void`	InitializeInternal
`public`	`void`	ResetValue
`public`	`Response<ExecutionResponseStatus>`	Execute
`protected abstract`	`Response<CvarSetResponseStatus>`	SetValue
`public`	`string`	GetHelp
`public virtual`	`string`	DisplayValue

Event Descriptions

ValueChanged

Called when the value has been changed.
Passes the new value as an argument to the consumer method.

This is useful for updating information using the observer pattern.

Example(s):

DifficultyCVar.ValueChanged += OnDifficultyChanged;

void OnDifficultyChanged(int newDifficulty)
{
    GameManager.Difficulty = newDifficulty;
}

ValueInvalidated

Called when the value has been changed.
Does NOT pass a value to the consumer method.

This is useful when several CVars share execution method.

Example(s):

CrosshairLengthCVar.ValueInvalidated += OnCrosshairChanged;
CrosshairThicknessCVar.ValueInvalidated += OnCrosshairChanged;
CrosshairColorCVar.ValueInvalidated += OnCrosshairChanged;

void OnCrosshairChanged()
{
    CrosshairManager.ReRender(
        CrosshairLengthCVar.Value,
        CrosshairThicknessCVar.Value,
        CrosshairColorCVar.Value
    );
}

Property Descriptions

Value

The current value.
Automatically handles value comparison and event triggering.
ValueChanged and ValueInvalidated are only called if the new value is not equal to the old value.

This saves performance on event invokation overhead.

IsModified

A shorthand for checking if the current value is not the original, expected value.
This can be used by saving systems to occlude default CVars, which allows for delta-configurations (only save what has been changed).

Behind the scenes, this is the full signature.

public bool IsModified => !EqualityComparer<T>.Default.Equals(_value, _defaultValue);

FormattedValue

Shorthand that displays the formatted value of a CVar.
It does so by utilizing the virtual method DisplayValue.

Persist

This is a Editor facing flag that decides whether or not the CVar should persist between sessions.

By default this only allows the CVar to be saved in the PersistentCVarRegistry. From there, one may opt-in for the built in userconfig .cfg system, or build their own using the PersistentCVarRegistry api.

IsCheat

This is a Editor facing flag that decides whether or not the CVar is considered a cheat.

CVars marked as cheats may only be edited by the system. Players are unable to edit them without entering cheatmode.

See also: ExecutionSource

CurrentValueDisplay

Shorthand property for getting the user-facing (UI-friendly) format of the current value. Used by the ConsoleFormatter to structure help messages.

Caution

CurrentValueDisplay shoud never be overridden directly by CVar variants.
Instead, they override the DisplayValue method provided by.

DefaultValueDisplay

Shorthand property for getting the user-facing (UI-friendly) format of the current value. Used by the ConsoleFormatter to structure help messages.

Caution

DefaultValueDisplay shoud never be overridden directly by CVar variants.
Instead, they override the DisplayValue method provided by.

Description

This is a Editor facing flag that sets the description of the CVar.

This description is used by the LongDesc prefaces the DescriptionInternal.
It can be arbitrarily long or short and serves as a description for the specific CVar resource, rather than the CVar type.

Example(s):

Crosshair length variable. 
Used by the CrosshairManager when rendering the crosshair on screen.

Signature

Fully automatic "command" signature for the CVar.
Each CVar automatically registers themselves to the RuntimeExecutableRegistry as an executable with the resource filename as the signature.

Note

Signatures are automatically parsed at runtime to ensure no spaces or trailing whitespaces exists.
Trailing whitespaces are trimmed, and spaces are replaced with underscores.

ShortDesc

Handled automatically by the root class (this).
ShortDesc is a required property for all IRuntimeExecutables and is used by help formatters and executable lists.

Behind the scenes, this is the full signature.

public string ShortDesc => $"View or set the value of {Signature}";

Note

Not having ShortDesc being virtually scoped is intentional.
When showing help for the executable signature it should be explicitly clear that it is a CVar shortcut, and that the command only serves and invokes the CVars Execute method.

Details about what the command does comes from the help formatter and long description.

LongDesc

Handled automatically by the root class (this).
LongDesc is the canonical long description of any executable and is hardwired for CVars to return both the resource description and the internal description.

Behind the scenes, this is the full signature.

public string LongDesc => $"{Description}\n{DescriptionInternal}";

DisplayType

This is the UI-friendly name of the type and is used to display the resource type in the console and logs. It is not designed to be parseable. However, all default CVars included in PikeConsole follow the strict naming pattern: CVar_Type

Example(s):

// Excerpt from CVarEnum.cs
public override string DisplayType => "CVar_Enum";

// Excerpt from CVarBool.cs
public override string DisplayType => "CVar_Bool";

// Excerpt from CVarInt.cs
public override string DisplayType => "CVar_Int";

// . . .

Usage

This is the UI-friendly, human readable usage instructions for the CVar.
Ideally it is kept short and concise for better parsing with the help command, but there is no arbitrary length limit.

By default it's formatted as $"{Signature} [new value]" for all CVars, but is overrideable for advanced extentions.

Behind the scenes, this is the full signature.

public virtual string Usage => $"{Signature} [new value]";

_defaultValue

The de-facto default value of the CVar resource instance.
This is set in the Godot editor by the designer.

CVar resources are automatically set to their default value when initialized or reset using the ResetValue method.

Note

If you are using the user configuration system the values are first set to their default values, and then overridden by the user profile initializer at startup.

_value

The de-facto current value of the CVar resource instance.
Unless the Persist flag is set (and the user configuration system is active), this value is per-session scoped. Closing and opening the runtime will reset the value to its default automatically.

DescriptionInternal

The META description for the CVar type.
The structure of this is fully arbitrary and just serves as an entry point for advanced extentions to list critical typ information.

Example(s):

excerpt from CVarEnum.cs.

protected override string DescriptionInternal => _cachedHelpLst;

protected override void InitializeInternal()
{
    // . . .
    StringBuilder sb = new("OPTIONS:\n");
    for (int i = 0; i < _options.Length; i++)
        sb.Append($"\t{i} = {_options[i]}\n");

    _cachedHelpLst = sb.ToString();
}

Method Descriptions

Initialize

Signature: public void Initialize()

Takes no parameters

Description:
Method used to add the CVar into the RuntimeExecutableRegistry and PersistentCVarRegistry. This is called automatically by the CVarCrawler inside the addons autoloader.

This method cannot be overridden. To extend the initializsation logic, see InitializeInternal.

Warning

If CVars are used as intended, this method never has to be called by any user of this framework. It is called autoamtically by the CVarCrawler for all CVar resources in the designated CVar directory and all of its child directories.

The only exception is for internal system initializations where CVars are defined outside of the designated CVar folder, as is the case with PikeConsoles cheatmode CVar and others located at addons/PikeConsole/Config/variables.

Example:

Excerpt from CVarCrawler.cs.

// . . .
Resource loadedResource = ResourceLoader.Load(fullPath);

if (loadedResource is ICVar cvar)
{
    cvar.Initialize();
}

InitializeInternal

Signature: protected virtual void InitializeInternal()

Takes no parameters

Description:
Method used to extend initialization logic and apply things like internal caching or fetching. This is called automatically at the end of Initialize, which itself is automatically called by the CVarCrawlerautoload at runtime initialization.

Example:

Excerpt from CVarEnum.cs.

// At CVar initialization, pre-cache all options to 
// improve runtime performance and text processing speed
protected override void InitializeInternal()
{
    // . . .
    StringBuilder sb = new("OPTIONS:\n");
    for (int i = 0; i < _options.Length; i++)
        sb.Append($"\t{i} = {_options[i]}\n");

    _cachedHelpLst = sb.ToString();
}

ResetValue

Signature: public void ResetValue()

Takes no parameters

Description:
Resets the value of the CVar back to its default value.
If the value is a persistent value and the new value is not equal to the old, the PersistentCVarRegistry sends an update event that is consumed by the user configuration storage (if it's enabled).

Example:

Hypothetical method that resets all user settings in a GUI within an optional scope.

public void ResetAllSettings(string scope = string.Empty)
{
    foreach(ICVar setting in allSettings)
    {
        if(string.IsNullOrWhitespace(scope))
            setting.ResetValue();
        else if(setting.Signature.StartsWith(scope))
            setting.ResetValue();
    }
}

Execute

Signature: public Response<ExecutionResponseStatus> Execute(ExecutionSource executionSource, string[] args)

Warning

CVars should not be set through code using the execution method unless it is necessary and used with intention. This method is used to map the CVar value to the RuntimeExecutionSystem and is mainly invoked through the means of a console or config file.

To set a CVar from code you should always manage the Value property directly.

When making a custom runtime console StatementExecutor should be used as the definitive entry point!

Example:

// This automatically runs like a system user and runs potential persistance events.
_gravityModifierCVar.Value = 800f;

Parameter details (Click to expand)

ExecutionSource : executionSource: The definite caller of this execution. Could be a player through the console / player config file, or the game itself through internal systems. Example: ExecutionSource.Player
string[] : args: The unparsed arguments passed to the CVar. If they end with the ram only flag, the flag is read and stripped before passing the arguments into the SetValue method.; Example:
["800", "ram_only"] In this example SetValue will be called using: SetValue(["800"]).
Since ram_only was used the value will not persist.

Description:
API entry point that makes CVars agnostically executable from outside systems.
This is mainly used by the StatementExecutor and should not be regularly used by users of this framework.

Example:

Excerpt from StatementExecutor.cs.

// . . .
if (RuntimeExecutableRegistry.TryGetExecutable(signature, out IRuntimeExecutable executable))
{
    Response<ExecutionResponseStatus> response = executable.Execute(executionSource, args);
    // . . . 
}

SetValue

Signature: protected abstract Response<CvarSetResponseStatus> SetValue(ReadOnlySpan<string> args);

Parameter details (Click to expand)

ReadOnlySpan<string> : args: The argument string array. Passed as ReadOnlySpan<string> for performance and mutability safety.

Example: ["800"]

Description:
This method handles the actual parsing and setting of data when calling the Execute method.
It is overridden within each CVar resource type and serves as the definite ruleset for what arguments are parsable.

Tip

This method is best combined with the ArgumentParser for the best results and developer experience.

Example(s):

Excerpt from CVarEnum.cs.
Note that the value is set using the Value property. The value MUST be set within the method.

public override Response<CvarSetResponseStatus> SetValue(ReadOnlySpan<string> args)
{
    if (!ArgumentParser.ValidateCount(args, 1, out string error))
        return new(CvarSetResponseStatus.InvalidArgs, error);

    if (!ArgumentParser.TryParseEnum(args[0], _options, out int index, out error))
        return new(CvarSetResponseStatus.Failed, error);

    if (Value == index)
        return new(CvarSetResponseStatus.NoChange, null);

    Value = index;
    return new(CvarSetResponseStatus.Success, null);
}

GetHelp

Signature: public string GetHelp()

Takes no parameters

Description:
Returns a human readable string with any help regarding the command by automatically interpolating all information about the IRuntimeExecutable.

The primary consumer of this method is the default command help, which prints information about runtime executables into the runtime console.

Extended knowledge

All IRuntimeExecutables get their help formatted from the ConsoleFormatter, like so:

    public string GetHelp() => ConsoleFormatter.FormatHelp(this);

This is an agressively inlined method that standarizes the text and outputs it the same no matter the caller.
Behind the scenes, this is the actual method being called:

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static string FormatHelp(IRuntimeExecutable rte)
{
    return $"Signature: {rte.Signature}\nIs cheat: {rte.IsCheat}\nDescription: {rte.ShortDesc}\nType: {rte.DisplayType.ToUpper()}\nUsage: {rte.Usage}\n{rte.LongDesc}";
}

Example(s):

Usage within a CVar.

[Export] CVarFloat _gravityModifierCVar;

protected override void _EnterTree() => 
    PikeConsole.Log(LogTarget.All, $"{_gravityModifierCVar.GetHelp()}");

DisplayValue

Signature: public virtual string DisplayValue(T value)

Parameter details (Click to expand)

T : value: Any value of type T (the same as this CVar resource instance).
Example: ["400"]

Description:
Takes any value of type T and returns a human readable / UI friendly representation for that value.

This method is used to parse othervise complex or unreadable data into something that would make sense when reading the value back. Such as the case with enums or vectors.

Example(s):

Excerpt from CVarEnum.cs.

public override string DisplayValue(int value) => 
    $"{value} ({_options[value]})";

This results in an output like:

1 (Medium)

Excerpt from CVarColor.cs.

public override string DisplayValue(Color value) 
    => $"({value.R8}, {value.G8}, {value.B8}, {value.A8}) | #{value.ToHtml()}";

For the color green, this results in an output like:

(0, 255, 0, 255) | #00ff00ff