Export Data

Exports documents into a file.

Command

# local game data (windows)
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "c:\my app\gamedata.json" \
  --schemas Character \
  --output "c:\my app\characters.json" \
  --outputFormat json

# remote game data
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --schemas Character \
  --output "./characters.json" \
  --outputFormat json \
  --credentials "<API-Key>"

Parameters

--dataBase

Absolute or relative path to game data. Use quotation marks if your path contains spaces.

# local file
--dataBase "c:\my app\gamedata.json"

# remote server
--dataBase "https://charon.live/view/data/My_Game/develop/"
--credentials

The API key used to access remote server in case of –dataBase being URL.

--schemas

A list of types of documents (schemas) to export. By default all schemas EXCEPT metadata are exported.

  • Use space to separate multiple schemas.

  • You can use wildcards (*) at the beginning and end of names.

  • You can use identifiers in {} instead of names.

  • You can exclude certain names by using an exclamation mark (!) at the beginning of their names.

# schema name
--schemas Character
--schemas Character Item

# all (default)
--schemas *

# masks
--schemas Char*
--schemas *Modifier
--schemas *Mod*

# schema id
--schemas {18d4bf318f3c49688087dbed}

# negation
--schemas Char* !Character
--schemas !*Item*

# excluding system schemas (Schema, SchemaProperty, ProjectSettings)
--schemas ![system]
--properties

A list of properties or property types to export. By default all properties are exported.

  • Id property always included

  • Use space to separate multiple properties.

  • You can use wildcards (*) at the beginning and end of names.

  • You can use identifiers in {} instead of names.

  • You can exclude certain names by using an exclamation mark (!) at the beginning of their names.

  • You can use data type in [] instead of names.

--languages

List of languages to keep in exported data. Language’s english name is used or language tag (BCP 47).

Use DATA I18N LANGUAGES to get list of used languages.

  • Use space to separate multiple languages

  • You can use wildcards (*) at the beginning and end of names.

  • You can use LCID or CultureInfo.Name in {} instead of the name.

  • You can exclude certain names by using an exclamation mark (!) at the beginning of their names.

# language tag (BCP 47)
--languages {en-US}

# language name
--languages "Spanish (Spain)"

# language name mask
--languages Spanish*

# language LCID
--languages {3082}

# negation and masks
--languages !Spanish*
--languages Spanish* !{es-Es}
--mode

Export mode controls stripping and inclusion rules for exported data.

# (default)
--mode normal

--mode publication
--mode extraction
--mode localization
normal

Export all specified documents defined in –schemas. This mode ensures that the exported graph of documents remains valid by including any necessary additional documents to avoid any broken references.

publication

Same as –mode normal, but shaped for the game: localization for languages outside –languages is stripped, and the file level ToolsVersion, RevisionHash and ChangeNumber fields are written into the output. System schemas and the project settings document are kept - the generated code requires them and refuses to load a file without them.

extraction

Export only the specified –schemas without exporting any referenced documents. In this mode, the exported graph of documents may contain broken references. It is recommended to use the import –mode safeupdate when importing this data back.

localization

Same as –mode extraction but only LocalizedText properties are exported.

--output

Path to a exported data file. If the file exists, it will be overwritten. The directory must already exist. Alternatively, you can output to Standard Error, Standard Output, /dev/null, or a URL.

# standard output (default)
--output out
--output con

# standard error
--output err

# null device
--output null

# absolute path (windows)
--output "c:\my app\document.json"

# absolute path (unix)
--output /user/data/document.json

# relative path (universal)
--output "./document.json"

# remote location (HTTP)
--output "http://example.com/document.json"

# remote location with authentication (FTP)
--output "ftp://user:password@example.com/document.json"
--outputFormat

Format of exported data.

# JSON (default)
--outputFormat json

# BSON
--outputFormat bson

# Message Pack
--outputFormat msgpack

# XML (removed in 2025.1.1)
--outputFormat xml

# XLSX Spreadsheet
--outputFormat xlsx
--outputFormattingOptions

Additional options for specified format.

This command supports universal parameters.

Output

The exported data follows the general game data structure, but omits ToolsVersion, RevisionHash, and ChangeNumber when the export mode is not set to publication.

{
  "Collections":
  {
    "Character":
    [
      {
        "Id": "Knight"

        /* rest of properties of document */
      },
      {
        "Id": "Templar"

        /* rest of properties of document */
      },
      // ...
    ]
  }
}

Modifying Exported Data with yq

The exported data can be accessed or modified using the yq tool, a lightweight and portable command-line YAML, JSON, and XML processor. yq uses jq-like syntax and supports common operations for manipulating structured data.

To use yq with exported JSON data:

  1. Install `yq`: Follow the installation instructions from the official yq documentation: https://mikefarah.gitbook.io/yq/.

  2. Query Data: Use yq to query specific fields or values from the exported JSON file.

    # Query a specific field
yq '.Collections.Character[0].name' characters.json

  3. Modify Data: Use yq to update or add fields in the exported JSON file.

    # Export data
dnx dotnet-charon -- DATA EXPORT \
  --dataBase gamedata.json \
  --schemas Character \
  --output characters.json

# Update a field
yq -i '.Collections.Character[0].name = "New Name"' characters.json

# Add a new field
yq -i '.Collections.Character[0].level = 10' characters.json

# Import data back
dnx dotnet-charon -- DATA IMPORT \
  --dataBase gamedata.json \
  --schemas Character \
  --input characters.json \
  --mode safeUpdate

  4. Convert Formats: yq can also convert between JSON, YAML, and other supported formats.

    # Convert JSON to YAML
yq -o=yaml characters.json > characters.yaml

For more advanced usage, refer to the yq documentation: https://mikefarah.gitbook.io/yq/.

See also