Json — C# API · Reckfell

class JsonReckfellSharpInherits Resource

Create Json, call Parse and use Data only after Error.Ok. Separately validate root type, fields and permitted values. The parser accepts trailing commas; it is not strict compatibility validation for every external JSON consumer.

When reusing an instance, diagnostics and retained text can remain from a previous call. The returned Error determines success. ParseString is shorter, but its Nil cannot distinguish failure from JSON null.

JSON numbers parse as Float. Store large identifiers in an agreed string format, or use FromNative/ToNative encoding for supported engine types. Ordinary Stringify does not automatically preserve Vector3, Resource or a C# class.

The example reads an integer score field from 0 to 1000000. Additional fields are allowed; syntax, root, type, finiteness and range are checked before returning the result.

C#
using System;
using Reckfell;

public static class JsonScoreExample
{
    public static bool TryReadScore(string text, out int score)
    {
        score = 0;
        using var document = new Json();
        if (document.Parse(text) != Error.Ok)
            return false;
        using Variant root = document.Data;
        if (root.VariantType != Variant.Type.Dictionary)
            return false;
        using var fields = root.AsReckfellDictionary();
        bool found = fields.TryGetValue("score", out Variant value);
        using (value)
        {
            if (!found || value.VariantType != Variant.Type.Float)
                return false;
            double number = value.AsDouble();
            if (!double.IsFinite(number) || number < 0 || number > 1_000_000
                || number != Math.Truncate(number))
                return false;
            score = (int)number;
            return true;
        }
    }
}

See saving games for a complete persistence workflow.

Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.

Constructors1

JsonConstructor

# Json

C#
public Json();

Creates an instance with Nil Data. Prefer a fresh instance for independent parsing: repeated Parse does not guarantee clearing previous data, retained text and diagnostics on every failure path.

Properties1

DataProperty

# Data

C#
public Variant Data { get; set; }

Parsed or explicitly assigned Variant value. Read a Parse result only after Error.Ok: failure can retain an old value, while another failure path produces Nil. Assigning Data clears GetParsedText(), but does not parse text or reset every diagnostic.

Methods10

FromNativeVariant

# FromNative

C#
public static Variant FromNative(Variant variant, bool fullObjects = false);

Encodes supported engine types into JSON-compatible values using its own tags, prefixes and structure. Returns a Variant, not text: call Stringify afterward if needed. This is the FromNative/ToNative pair protocol, not an ordinary JSON DTO.

Parameters
Name	Type	Default
`variant`	`Variant`	—
`fullObjects`	`bool`	`false`

variant

Engine value to encode. Not an arbitrary managed C# object; support follows Variant types.

fullObjects

Defaults to false: Object encoding is disallowed and can return Nil with a diagnostic. true enables supported object-property serialization, not a copy of all application state.

Returns Variant

Encoded Variant; unsupported/disallowed paths can produce Nil with diagnostics. Nil also encodes an original Nil.

GetDataVariant

# GetData

C#
public Variant GetData();

Returns Data. Contained Array/Dictionary values remain shared rather than becoming an independent deep clone. Dispose the returned Variant after use.

Returns Variant

Variant from Data. Check the latest Parse Error before interpreting it.

GetErrorLineint

# GetErrorLine

C#
public int GetErrorLine();

Returns the diagnostic line index from Parse. Counting starts at 0; success also sets 0, so inspect Error rather than using the line number to determine success.

Returns int

Zero-based line index; 0 does not distinguish success from a first-line failure.

GetErrorMessagestring

# GetErrorMessage

C#
public string GetErrorMessage();

Returns the stored parse diagnostic. Read it when Parse fails. In the current implementation, a later successful Parse can retain an old message; a nonempty string alone does not mean the latest call failed.

Returns string

Stored diagnostic, which can refer to an earlier failure.

GetParsedTextstring

# GetParsedText

C#
public string GetParsedText();

Returns the last text supplied to Parse with keepText: true, including failed input. keepText: false does not clear previously retained text. Assigning Data/SetData clears it. This is not a fresh serialization of Data.

Returns string

Retained input text, or an empty string when none. May not correspond to current Data.

ParseError

# Parse

C#
public Error Parse(string jsonText, bool keepText = false);

Parses text and returns Error. After Error.Ok, validate root type, required fields and ranges. The parser accepts some extensions such as trailing commas; it is not a strict format validator for every external system. Do not use Data after failure. A repeated object key retains the last value.

Parameters
Name	Type	Default
`jsonText`	`string`	—
`keepText`	`bool`	`false`

jsonText

Complete input text. The parser checks the document end but accepts some nonstrict syntax; successful parsing does not validate game requirements.

keepText

true retains the input string even on failure. false leaves a previously retained string intact; it is not a clear command.

Returns Error

Error.Ok when input is accepted; otherwise a failure code. Use this as the success indicator, rather than GetErrorMessage or Data.

ParseStringVariant

# ParseString

C#
public static Variant ParseString(string jsonString);

Shorthand parsing without a separate Error. Valid JSON null and failure both return Nil; failure also logs a native diagnostic. Use an instance Json.Parse to distinguish them.

Parameters
Name	Type	Default
`jsonString`	`string`	—

jsonString

JSON text. Use instance Parse instead to obtain a separate Error and diagnostic.

Returns Variant

Parsed Variant. Nil does not distinguish failure from valid JSON null.

SetDatavoid

# SetData

C#
public void SetData(Variant data);

Assigns Data and clears retained source text. Does not read JSON, validate a schema or automatically clear all information from a previous Parse.

Parameters
Name	Type	Default
`data`	`Variant`	—

data

Operation input. For Stringify, follow your JSON schema; for SetData, a direct Variant value, not text to parse.

Stringifystring

# Stringify

C#
public static string Stringify(Variant data, string indent = "", bool sortKeys = true, bool fullPrecision = false);

Converts a Variant to JSON text without writing a file. An integer Variant emits a decimal integer, but Parse reads JSON numbers as Float: large integers can lose precision. For ordinary JSON, define a schema, use string keys and finite numbers. Not complete serialization of arbitrary engine objects.

Parameters
Name	Type	Default
`data`	`Variant`	—
`indent`	`string`	`""`
`sortKeys`	`bool`	`true`
`fullPrecision`	`bool`	`false`

data

Operation input. For Stringify, follow your JSON schema; for SetData, a direct Variant value, not text to parse.

indent

Indentation per level. Empty produces compact output; use spaces or tabs for readable JSON. Arbitrary non-whitespace characters are inserted literally and can invalidate JSON.

sortKeys

Sort dictionary keys before output; defaults to true. Use string keys for external JSON. Sorting does not establish a universal canonical format.

fullPrecision

Use fuller Float formatting for exact double reading. Does not fix large-Int precision loss during later Parse or add standard JSON NaN/Infinity support.

Returns string

Generated text. NaN becomes null with a warning; Infinity becomes signed 1e99999. Not a portable round trip for nonfinite values; validate finiteness before writing.

ToNativeVariant

# ToNative

C#
public static Variant ToNative(Variant json, bool allowObjects = false);

Decodes a representation produced by FromNative. For text input, call Parse and check Error first. Do not treat arbitrary ordinary JSON as the encoded representation. Enabling allowObjects can create objects and assign properties/scripts: not schema validation or a sandbox.

Parameters
Name	Type	Default
`json`	`Variant`	—
`allowObjects`	`bool`	`false`

json

JSON-compatible Variant in FromNative format, not a JSON string to parse directly.

allowObjects

Defaults to false. true permits object creation during decoding; use only trusted encoded input with controlled types.

Returns Variant

Restored engine value; Nil can indicate failure or a valid original Nil.