Unity Plugin Overview

Charon is a versatile plugin tailored for Unity, designed to facilitate data-driven game design by allowing both developers and game designers to efficiently manage static game data, like units, items, missions, quests, and other. Charon elevates the experience by offering an editing UI directly in your web browser, enabling the modeling of diverse data structures suited to any game genre. It provides a user-friendly interface that requires no special skills for game designers, simplifying the process of data manipulation. For programmers, Charon streamlines development workflows by generating code to load game data seamlessly into the game.

Key Features

  • Data Modeling: Define game entities like characters, items, missions, quests, and dialogs to meet the specific needs of your game. Interconnect and fill these tables within one UI.

  • Error Control: Implements validation checks to verify the accuracy of input data, reducing the likelihood of errors that could impact gameplay or development.

  • Code Generation: Automates the creation of boilerplate code needed to work with your game data, significantly speeding up development time and reducing manual coding errors.

  • Spreadsheet Export/Import: Offers seamless integration with spreadsheet software, enabling you to effortlessly populate, edit, and manage your game data in a familiar environment.

  • Localization Export/Import: Simplifies the process of preparing game data for translation, making it straightforward to adapt your game for global audiences.

  • Modding Support: Empowers your gaming community by providing them with the tools to create and share mods, enhancing the longevity and depth of your game.

  • Dynamic Load: Facilitates the dynamic loading of game data, enabling features like A/B testing or the ability to push hot updates directly to your players.

Charon editor UI

Getting Started

Prerequisites

Unity plugin uses dotnet charon tool, which is a .NET Core application built for .NET 8.

  1. Download and install NET 8+.

  2. Make sure you have write access to %APPDATA%/Charon.

Checking Available .NET Versions

In terminal window run dotnet --list-sdks command:

# check for dotnet already installed
dotnet --list-sdks

Installation from Unity Asset Store

  1. Install the required software for your operating system.

  2. Ensure your Unity version is 2021.3 or later.

  3. Open the Charon plugin in the Unity Asset Store.

  4. Click Add To My Assets.

  5. Open the Unity Package Manager by navigating to Window → Package Manager.

  6. Wait for the package manager to populate the list.

  7. Select My Assets from the dropdown in the top left corner.

  8. Select Charon from the list and click Download. If it’s already downloaded, you will see an Import option.

Installation from GitHub

  1. Install the required software for your operating system.

  2. Clone or download the plugin source code from the GitHub repository.

  3. Create a <project-dir>/Packages/com.gamedevware.charon directory.

  4. Copy the plugin files from src/GameDevWare.Charon.Unity/Packages/com.gamedevware.charon into this directory.

  5. Restart Unity if necessary.

Core Concepts

Data-Driven Design Principles

Data-driven design emphasizes controlling gameplay through data rather than source code or blueprints. Game mechanics and processes are determined by structured data files. For example, instead of embedding damage calculations directly in the game’s source code, these are defined by data specifying weapon effects and the rules for their application. Similarly, mission progression is not hardcoded; it is outlined in editable text files, making these aspects of game design highly flexible. This approach not only facilitates quick adjustments during development but also simplifies adding modding support post-release.

Understanding the Plugin’s Architecture

Plugin Assets

Charon assets scheme in Unity

All game data information is stored in a JSON file within your project. The generated source code is used to load this data into the game. Additionally, a ScriptableObject asset will be created, which can be used to access game data from your scenes.

Charon asset Inspector view

Whenever there is a modification in the data structure within a JSON file, it is necessary to regenerate the C# source code and reimport the .asset file. To do this, select the .asset file and press the Synchronize button.

Working with the Plugin

Creating Game Data

To create a new game data file within the Unity Editor, open the Project window, right-click in the desired folder, and select the Create → Game Data menu option.

  1. Open the Project window and navigate to the desired folder.

  2. Right-click in the Project window and select Create → Game Data.

  3. Name your game data file and click the Create button.

  4. Wait for the source code and assets to be created in the specified folder and for the editor to recompile the scripts.

  5. Double-click the created .asset or .gdjs file to start editing.

Editing Game Data

To edit a game data file in the Unity Editor, open the Project window, find the corresponding .gdjs, .gdmp, or .asset file, and double-click it. This action opens a new web browser window featuring a user interface for editing the game data. Remember to Synchronize assets from the Inspector window after completing your edits.

Charon UI in Unity Editor

Advanced Features

Localization and Multi-Language Support

Charon facilitates multi-language text support through the Localizable Text data type. When creating a Schema, properties can be defined with various data types, including Localizable Text. Initially, all localizable text defaults to EN-us (US English). Additional languages can be added via Project Settings → Internationalization → Translation Languages in the Charon UI.

Exporting/importing localizable data.

Referencing Game Data in Scenes

The Charon plugin introduces a specific type for referencing documents within scenes, named GameDataDocumentReference. This type is part of the Charon package. To create such a reference, add a field with the GameDataDocumentReference type to your component class.

public class HeroComponent : MonoBehaviour
{
  public GameDataDocumentReference heroReference;
}

You can then configure it in the Inspector. Here is an example of a Game Data Document Reference used to point to a Hero document:

Charon document reference example screenshot

To get an instance of a document in your game code, call the GameDataDocumentReference.GetReferencedDocument<Hero>() method.

private void OnEnable()
{
  var hero = this.heroReference.GetReferencedDocument<Hero>();
  Debug.Log(hero.Name);
}

Work & Build Automation

To facilitate automation of work or builds, a programmatic interface for working with game data is provided. You can read more about it on the CharonCli class documentation page.

Feedback

We welcome and encourage feedback, particularly bug reports and suggestions, to help improve our tool. If you have any questions or would like to share your thoughts, please join our Discord community or reach out to us via email at support@gamedevware.com.

See also