dotnet-charon
2025.1.3
dotnet tool install --global dotnet-charon --version 2025.1.3
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local dotnet-charon --version 2025.1.3
#tool dotnet:?package=dotnet-charon&version=2025.1.3
nuke :add-package dotnet-charon --version 2025.1.3
Charon - Game Data Editor
Documentation • Discord • Website • Changelog • Issues
Plugins
[Unity Asset Store] [Unity OpenUPM] [Unreal Engine Marketplace]
Standalone
How to start with custom game engine → C# • TypeScript
Summary
Charon is a powerful data-driven game development tool designed to streamline the creation and management of static game data within Unity. It allows both developers and game designers to efficiently model and edit game entities such as characters, items, missions, quests, and more, directly within the Unity environment. Charon simplifies the process of data manipulation, offering a user-friendly interface and automatic source code generation, which significantly reduces development time and minimizes manual coding errors. Charon also offers support for working with text in multiple languages, with easy loading and unloading of translated text.
With Charon, game developers can focus on creating engaging gameplay experiences without worrying about the technical details of managing game data. It is available in three deployment variants, including a standalone/offline application, web application, Unity and Unreal Engine plugins.
Why Choose Charon?
Charon replaces traditional spreadsheets or config files with an in-game database, offering a structured and efficient way to manage game data. It allows developers to focus on creating engaging gameplay experiences without worrying about the technical details of data management.
Is It Free?
The offline version, CLI and plugins are completely free and have no restrictions. They are distributed under a free license and allow you to distribute tools along with the game for modding games.
The online version, which allows working in large teams on shared game data, requires a subscription.
What is Charon
It is a .NET 8 console application that can be used as a command-line tool for performing CRUD operations with your game data, or as an HTTP Server to provide a UI for modeling and editing your game data. There are plugins for Unity and Unreal Engine that provide a more integrated experience while using Charon.
As with any .NET application, it can be launched as is on Windows, macOS and Linux and via dotnet.
How it works
To get started with Charon, you’ll need the following:
- The
dotnetruntime installed. - Either Unity [Asset] [OpenUPM], the Unreal Engine plugin, or the standalone tool, which you can install globally using the command:
dotnet tool install dotnet-charon --global
Once set up, follow these steps:
- Create an empty
gamedata.jsonfile or usedotnet charon INIT gamedata.jsoncommand. - Launch the Charon tool by running:
This command starts an HTTP server and automatically opens the Charon UI in your default web browser.dotnet charon gamedata.json - Use the intuitive web-based UI to design and edit your game data.
- After editing, utilize Charon’s source code generator to produce engine-specific source code for your game data.
- Integrate the generated source code into your game project. This allows you to load the
gamedata.jsonfile into your game in a structured and type-safe way, ensuring seamless and error-free data usage.
C# Code Example
using System.IO;
using var fileStream = File.OpenRead("gamedata.json"); // or .gdjs
var gameData = new GameData(fileStream, new Formatters.GameDataLoadOptions { Format = Formatters.Format.Json });
var heroes = gameData.Heroes.AsList // -> IReadOnlyList<Hero>
// or
var heroById = gameData.AllHeroes.Find("Arbalest"); // -> Hero | null
C++ Code Example
#include "UGameData.h"
TSoftObjectPtr<UGameData> GameDataPtr = TEXT("/Game/Content/GameData");
auto GameData = GameDataPtr.LoadSynchronous(); // -> UGameData*
auto Heroes = GameData->Heroes; // -> TMap<FString,UHero*>
auto HeroById = GameData->Heroes.Find(TEXT("Arbalest")); // -> UHero**
TypeScript Code Example
import { GameData } from './game.data';
import { Formatters } from './formatters';
// Node.js
import { readFileSync } from 'fs';
const gameDataStream = readFileSync(gameDataFilePath);
// Blob or File
const gameDataStream = gameDataFileBlob.arrayBuffer();
// XMLHttpRequest (XHR)
// gameDataRequest.responseType -> "arraybuffer"
const gameDataStream = gameDataRequest.response;
const gameData = new GameData(gameDataStream, {
format: Formatters.GameDataFormat.Json
});
let heroes = gameData.heroes; // -> readonly Hero[]
let hero = gameData.heroesAll.find("Arbalest"); // -> Hero | undefined
Haxe Code Example
import GameData;
import Formatters;
import haxe.io.Path;
sys.io.File;
var input = File.read("RpgGameData.gdjs"); // or .json
var options = new GameDataLoadOptions();
options.format = GameDataFormat.Json;
var gameData = new GameData(input, options);
var allHeroes = gameData.heroesAll.list // -> ReadOnlyArray<Hero>
var heroById = gameData.heroesAll.get("Arbalest"); // -> Hero
License
- Generated Code - MIT
- Plugins:
- Unreal Engine - MIT
- Unity - Unity Asset Store License
- Charon - CC BY-ND - can freely use and can redistribute, as long as it is passed along unchanged and in whole.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. |
This package has no dependencies.
# 2025.1.3
- Fixed error when `%APPDATA%/Charon` or `%DOTNET_CONTENTROOT%` directory is missing on application start.
# 2025.1.2
## General
- Restored file upload/download functionality inside the Unreal Engine CEF window. This re-enables the feature in UE versions after 5.2, where it was disabled by Epic Games.
- Fixed a potential hang when multiple save calls were made concurrently, preventing race conditions under high CPU load.
- Corrected a typo in the C++ code generator affecting the property decorator: `UPROPERTY(BlueprintReadOnly, VisibleAnywhere)`.
- Updated the Terms of Service for the online application to clarify data ownership and reduce the scope of platform control.
## Game Data Editing
- Updated the RPG Game Project example to include new features such as custom layouts and templated display text for schemas.
- Fixed an issue where overflow error messages displayed `[object Object]` placeholders instead of actual min/max values.
- Improved overflow detection to correctly handle integers larger than 2^53 without reporting false overflows.
## Code Generation
- Updated copyright notices to dynamically use the current year instead of a fixed year.
## User Interface
- Added an option to specify languages when publishing data in Unreal Engine.
- Introduced a new window for previewing publication issues.
## Web Application
- Fixed an issue with GitHub authentication caused by a JSON parsing error.
# 2025.1.1
## Breaking Changes
- **EXPORT:** XML format has been discontinued.
- **EXPORT:** Export no longer auto-includes containing schemas for the selected schema list. If a schema is embedded in another, you must explicitly specify the root schema for export.
- **EXPORT:** Export no longer auto-exclude system schemas for empty or '*' schema list. Use explicit exclusion token ``* ![system]`` for same purpose.
- **EXPORT:** The primary translation language text is now always the first member in JSON, MessagePack, and XLSX data formats, with the remaining languages sorted alphabetically. Previously, languages were sorted alphabetically by their BCP-47 language IDs.
- **EXPORT:** The order of collections in the `Collections` field has changed. `Project Settings` and `Schemas` now appear first, followed by all other collections in alphabetical order.
- **CLI:** The `DATA LIST` command now returns a standard game data document structure, similar to the `DATA EXPORT` command, instead of an array of documents.
- **CLI:** The built-in T4 transformation tool has been removed from the `GENERATE TEXT` command. Use the external [`dotnet-t4`](https://github.com/mono/t4) tool instead.
## General Improvements
- The default deployment has switched from a .NET Framework tool package to a `dotnet tool` NuGet package.
- Installing and running Charon CLI now requires only two commands:
```sh
dotnet tool install -g dotnet-charon
dotnet charon ...
```
- New JSON, BSON, and MessagePack formatters generate less memory garbage and offer better performance.
- The switch to the .NET Core runtime improves memory usage and overall performance compared to .NET Framework.
## User Interface
- Added language IDs (BCP-47) alongside language names in **Project → Internationalization**.
- Fixed an issue where limited resource allowances (AI Tokens, Machine Translation) were not rolling over at the end of the month.
- Added an option to hide schemas from the left-side menu, accessible via **Actions → Advanced Options**.
- Added **Next/Previous** navigation buttons in the document form UI, allowing users to browse documents without returning to the document list.
- Added a **Create** button in the document form UI under **Actions → Create**, allowing document creation without navigating back to the document list.
- Introduced a **Form/Layout/JSON** view switch in the bottom-right corner of the document form. Layout view is only available for schemas.
- Added options to rearrange and group schema properties within the form editor.
- Refactored the **Formula Type** lookup to display all supported public types when running inside Unity or Unreal Engine editors. Otherwise, it defaults to a subset of supported types (e.g., primitives, `Math`, etc.).
## Game Data Editing
- The **Extraction** export mode now behaves the same as **Normal**, ensuring a valid document graph without broken references.
- The `Id` column in exported XLSX spreadsheets is no longer hidden when values are auto-generated.
- Added document count validation for **Component** and **Settings** schema types, warning when the incorrect number of documents are present.
- The schema name `SchemaPropertyType` is now reserved and cannot be used for custom schemas.
- Deprecated the C# 4.3 language target—avoid using it in new projects.
- Added schema and property specification keys for code generation:
- `csAttribute`, `uecppAttribute`, `haxeAttribute`, `tsAttribute` – allows adding arbitrary attributes to generated classes and properties.
- `csBaseType`, `uecppBaseType`, `haxeBaseType`, `tsBaseType` – allows changing the base type of generated classes.
- Added `SchemaId` and `SchemaName` static fields to each generated class in all source code languages.
## Command-Line Interface (CLI)
- Added a shortcut command:
```sh
dotnet charon <filename>
```
This starts the application with the specified file, launches an HTTP server with default parameters, and opens the UI in the default browser.
- Added a command to initialize an empty game data file:
```sh
dotnet charon INIT <filename>
```
- The CLI now reuses an existing HTTP server instance when reopening the same game data file with `dotnet charon [filename]`, using an implicit lock file in `%AppData%/Charon/`.
- Configured `appsettings.json` to be loaded from the base application directory, with overrides from `%APPDATA%/Charon/appsettings.json`.
- Logs, preferences, and lock files are now stored in `%APPDATA%/Charon/`.
- Added a new command to add a translation language:
```sh
dotnet charon DATA I18N ADDLANGUAGE
```
- Modified `dotnet charon DATA IMPORT` and `dotnet charon DATA I18N IMPORT` to output import report in specified format. By default, it output to `nul`.
# 2025.1.2
## User Interface
- Fixed file download/upload inside Unreal Engine browser window. This will allow upload and download files from embedded browser in Unreal Engine editor version older than 5.2.