├── .config └── dotnet-tools.json ├── .github └── workflows │ └── documentation.yaml ├── .gitignore ├── LICENSE ├── PRIVACY_POLICY.md ├── README.md ├── TERMS_OF_SERVICE.md ├── docs ├── _static │ └── js │ │ └── cloudflare_analytics.js ├── advanced │ ├── command_line.rst │ ├── commands │ │ ├── data_apply_patch.rst │ │ ├── data_backup.rst │ │ ├── data_create.rst │ │ ├── data_create_patch.rst │ │ ├── data_delete.rst │ │ ├── data_export.rst │ │ ├── data_find.rst │ │ ├── data_i18n_add_language.rst │ │ ├── data_i18n_export.rst │ │ ├── data_i18n_import.rst │ │ ├── data_i18n_languages.rst │ │ ├── data_import.rst │ │ ├── data_list.rst │ │ ├── data_restore.rst │ │ ├── data_update.rst │ │ ├── data_validate.rst │ │ ├── generate_csharp_code.rst │ │ ├── generate_haxe_code.rst │ │ ├── generate_templates.rst │ │ ├── generate_text.rst │ │ ├── generate_typescript_code.rst │ │ ├── generate_uecpp_code.rst │ │ ├── init.rst │ │ ├── remote_input_output.rst │ │ ├── serve.rst │ │ ├── universal_parameters.rst │ │ └── version.rst │ ├── extensions │ │ ├── creating_angular_extension.rst │ │ ├── creating_react_extension.rst │ │ ├── implementing_property_editor.rst │ │ └── overview.rst │ ├── game_data_structure.rst │ ├── import_export.rst │ ├── internationalization.rst │ ├── logs.rst │ └── reset_preferences.rst ├── assets │ ├── cover_github.png │ ├── dashboard.png │ ├── document_collection.png │ ├── document_form.png │ ├── documents_import.png │ ├── editor_custom_editor.png │ ├── editor_screenshot.png │ ├── how_it_works.png │ ├── project_settings_extensions.png │ ├── schema_designer_select_editor.png │ ├── schema_designer_select_extension_editor.png │ ├── ue_document_reference.png │ ├── ue_editor_screenshot.png │ ├── ue_plugin_assets.png │ ├── unity_document_reference.png │ ├── unity_edit_gamedata.png │ ├── unity_logo.svg │ ├── unity_migrate_window.png │ ├── unity_plugin_asset_inspector.png │ ├── unity_plugin_assets.png │ └── unreal_engine_logo.svg ├── conf.py ├── faq.rst ├── favicon.ico ├── gamedata │ ├── basics.rst │ ├── creating_schema.rst │ ├── datatypes │ │ ├── all │ │ │ ├── date.rst │ │ │ ├── document.rst │ │ │ ├── document_collection.rst │ │ │ ├── formula.rst │ │ │ ├── integer.rst │ │ │ ├── localized_text.rst │ │ │ ├── logical.rst │ │ │ ├── multi_pick_list.rst │ │ │ ├── number.rst │ │ │ ├── pick_list.rst │ │ │ ├── reference.rst │ │ │ ├── reference_collection.rst │ │ │ ├── text.rst │ │ │ └── time.rst │ │ ├── list.rst │ │ └── sub │ │ │ ├── asset.rst │ │ │ ├── rectangle.rst │ │ │ ├── rectangle_int.rst │ │ │ ├── tags.rst │ │ │ ├── vector.rst │ │ │ └── vector_int.rst │ ├── define_schema_property.png │ ├── design_entities.png │ ├── enemy_schema_example.png │ ├── filling_documents.rst │ ├── general_design.png │ ├── generating_source_code.rst │ ├── inheritance.rst │ ├── inheritance_aggregation.png │ ├── inheritance_composition.png │ ├── inheritance_merging.png │ ├── inheritance_start.png │ ├── properties │ │ ├── id_property.rst │ │ ├── property.rst │ │ └── shared_property.rst │ ├── publication.rst │ ├── schemas │ │ ├── display_text_template.rst │ │ ├── schema.rst │ │ └── specification.rst │ ├── source_code_features.csv │ ├── working_with_csharp_code_4_0.rst │ ├── working_with_csharp_code_7_3.rst │ ├── working_with_haxe_code.rst │ ├── working_with_type_script_code.rst │ └── working_with_uecpp_code_.rst ├── glossary.rst ├── index.rst ├── openapi.yml ├── readme.md ├── standalone │ └── overview.rst ├── unity │ ├── charon_cli.rst │ ├── migrating_from_legacy_version.rst │ ├── migrating_to_web.rst │ └── overview.rst ├── unreal_engine │ ├── creating_game_data.rst │ └── overview.rst └── web │ ├── cli_access_to_web_project.rst │ ├── migrating_to_web.rst │ ├── overview.rst │ ├── permission_and_roles.rst │ └── rest.rst └── scripts └── bootstrap ├── RunCharon.bat ├── RunCharon.sh ├── RunT4.bat └── RunT4.sh /.config/dotnet-tools.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 1, 3 | "isRoot": true, 4 | "tools": { 5 | "dotnet-charon": { 6 | "version": "2025.0.0", 7 | "commands": [ 8 | "charon" 9 | ], 10 | "rollForward": false 11 | } 12 | } 13 | } -------------------------------------------------------------------------------- /.github/workflows/documentation.yaml: -------------------------------------------------------------------------------- 1 | name: Build Documentation Pages (Sphinx) 2 | on: 3 | push: 4 | branches: 5 | - 'main' 6 | paths: 7 | - 'docs/**' 8 | workflow_dispatch: {} 9 | permissions: 10 | contents: write 11 | jobs: 12 | docs: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@v3 16 | - uses: actions/setup-python@v3 17 | - uses: ts-graphviz/setup-graphviz@v2 18 | - name: Install dependencies 19 | run: | 20 | pip install sphinx sphinx_rtd_theme sphinxcontrib-openapi sphinx-copybutton sphinx-tabs rst2pdf 21 | - name: Sphinx build 22 | run: | 23 | sphinx-build docs _build && sphinx-build -b pdf docs _build/pdf 24 | - name: Deploy 25 | uses: peaceiris/actions-gh-pages@v3 26 | if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} 27 | with: 28 | publish_branch: gh-pages 29 | github_token: ${{ secrets.GITHUB_TOKEN }} 30 | publish_dir: _build/ 31 | force_orphan: true 32 | -------------------------------------------------------------------------------- /docs/_static/js/cloudflare_analytics.js: -------------------------------------------------------------------------------- 1 | // source/_static/js/cloudflare_analytics.js 2 | (function() { 3 | var script = document.createElement('script'); 4 | script.defer = true; 5 | script.src = 'https://static.cloudflareinsights.com/beacon.min.js'; 6 | script.setAttribute('data-cf-beacon', '{"token": "1759cfae2eab4ff6b2f3ac7339eab4e5"}'); 7 | document.head.appendChild(script); 8 | })(); -------------------------------------------------------------------------------- /docs/advanced/command_line.rst: -------------------------------------------------------------------------------- 1 | Command Line Interface (CLI) 2 | ============================ 3 | 4 | Most of Charon functionality could be accessed via CLI commands. The application itself uses the `getops `_ syntax. 5 | You should be familiar with terminal on your OS to fully tap potential of CLI. 6 | 7 | .. _CommandLine_Installation: 8 | 9 | Installation 10 | ------------ 11 | 12 | Download and install `NET 8+ `_. 13 | 14 | Option 1: dotnet tool (recommended) 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | The easiest way to install is to use the infrastructure provided by the `dotnet tool `_. 17 | 18 | .. code-block:: bash 19 | 20 | # install charon globally 21 | dotnet tool install -g dotnet-charon 22 | 23 | # install charon in current working directory 24 | dotnet tool install dotnet-charon --local --create-manifest-if-needed 25 | 26 | To update current tool use following commands: 27 | 28 | .. code-block:: bash 29 | 30 | # update global tool 31 | dotnet tool update --global dotnet-charon 32 | 33 | # update local tool 34 | dotnet tool update dotnet-charon --local 35 | 36 | Option 2: Bootstrap scripts 37 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 38 | 39 | Alternatively, you can use one of two bootstrap scripts: 40 | 41 | - `RunCharon.bat (Windows) `_ 42 | - `RunCharon.sh (Linux, MacOS) `_ 43 | 44 | Both scripts require the `dotnet `_ tool to be included in the system PATH. 45 | The scripts handle the installation of the Charon tool and ensure it stays up to date. 46 | 47 | .. tabs:: 48 | 49 | .. tab:: Windows 50 | 51 | .. code-block:: bash 52 | 53 | mkdir Charon 54 | cd Charon 55 | curl -O https://raw.githubusercontent.com/gamedevware/charon/main/scripts/bootstrap/RunCharon.bat 56 | 57 | .\RunCharon.bat DATA EXPORT --help 58 | # ^ 59 | # your command goes here 60 | 61 | .. tab:: Linux, MacOS 62 | 63 | .. code-block:: bash 64 | 65 | mkdir Charon 66 | cd Charon 67 | curl -O https://raw.githubusercontent.com/gamedevware/charon/main/scripts/bootstrap/RunCharon.bat 68 | 69 | chmod +x ./RunCharon.sh 70 | 71 | ./RunCharon.sh DATA EXPORT --help 72 | # ^ 73 | # your command goes here 74 | 75 | Command Syntax 76 | -------------- 77 | 78 | Commands have the following syntax: 79 | 80 | .. code-block:: bash 81 | 82 | dotnet charon COMMAND --parameterName 83 | 84 | # parameters can have more than one value. 85 | # Use space to separate values 86 | dotnet charon EXPORT --schemas Item Armor "Project Settings" Quest 87 | 88 | # if your value contains a space, put it inside the quotation marks. 89 | # Escape characters and other rules depend on the OS you are running. 90 | dotnet charon "c:\my application\my path.txt" 91 | 92 | # some parameters don't require a value (e.g. flag). 93 | dotnet charon VERSION --verbose 94 | 95 | Absolute and relative paths 96 | --------------------------- 97 | When running commands, it's crucial to be aware of whether you are using `absolute or relative paths `_ to files. 98 | 99 | Understanding Paths 100 | ~~~~~~~~~~~~~~~~~~~ 101 | 102 | 1. **Absolute Path**: 103 | An absolute path defines a file or directory's location in relation to the root directory. In Linux and macOS, it starts from the root ``/``, while in Windows, it begins with a drive letter (like ``C:\\``). 104 | 105 | - Example for Linux/macOS: ``/usr/local/bin`` 106 | - Example for Windows: ``C:\\Program Files\\mono`` 107 | 108 | 2. **Relative Path**: 109 | A relative path references a file or directory in relation to the current working directory, without starting with a root slash or drive letter. 110 | 111 | - Example: If currently in ``/home/user/Documents``, a file in ``/home/user/Documents/Projects`` would have the relative path ``Projects/FileName``. 112 | 113 | Usage in Terminals 114 | ~~~~~~~~~~~~~~~~~~ 115 | 116 | - **Windows Command Prompt**: 117 | Paths use backslashes (``\\``). Absolute paths start with a drive letter (like ``C:\\Users\\Name``), while relative paths use the file name or paths like ``subfolder\\file.txt``. 118 | 119 | - **macOS/Linux Terminal**: 120 | Paths are denoted with forward slashes (``/``). Absolute paths begin from the root (``/``), and relative paths use ``./`` for the current directory or ``../`` to go up one level. 121 | 122 | Getting Help Text 123 | ----------------- 124 | 125 | To display list of available commands add `--help` or `/?`. 126 | 127 | .. code-block:: bash 128 | 129 | dotnet charon --help 130 | 131 | #> Usage: dotnet charon [-- || (-- ...) ...] 132 | #> 133 | #> Verbs: 134 | #> DATA Data manipulation actions. 135 | #> GENERATE Code generation actions. 136 | #> VERSION Print version. 137 | 138 | dotnet charon DATA EXPORT --help 139 | 140 | #> Usage: 141 | #> DATA EXPORT --dataBase [--schemas []] [--properties []] [--languages []] [--output 142 | #> ] [--outputFormat ] [--outputFormattingOptions []] [--mode ] [--credentials [< 143 | #> TEXT>]] 144 | 145 | .. _CommandLine_Commands: 146 | 147 | .. toctree:: 148 | :caption: List of Commands 149 | :titlesonly: 150 | :glob: 151 | 152 | commands/* 153 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_apply_patch.rst: -------------------------------------------------------------------------------- 1 | Apply Patch 2 | =========== 3 | 4 | Applies patch created with :doc:`DATA CREATEPATCH ` command to a game data. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA APPLYPATCH --dataBase "c:\my app\gamedata.json" --input "c:\my app\gamedata_patch.json" --inputFormat json 19 | 20 | # remote game data 21 | dotnet charon DATA APPLYPATCH --dataBase "https://charon.live/view/data/My_Game/develop/" --input "./gamedata_patch.json" --inputFormat json --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --input 42 | Path to a file with patch to apply. Alternatively, you can use `Standart Input `_ or `URL `. 43 | 44 | .. code-block:: bash 45 | 46 | # standart input (default) 47 | --input in 48 | --input con 49 | 50 | # absolute path (windows) 51 | --input "c:\my app\gamedata_patch.json" 52 | 53 | # absolute path (unix) 54 | --input "/user/data/gamedata_patch.json" 55 | 56 | # relative path (universal) 57 | --input "./gamedata_patch.json" 58 | 59 | # remote location (HTTP) 60 | --input "http://example.com/gamedata_patch.json" 61 | 62 | # remote location with authentication (FTP) 63 | --input "ftp://user:password@example.com/gamedata_patch.json" 64 | 65 | --inputFormat 66 | Format of imported data. 67 | 68 | .. code-block:: bash 69 | 70 | # Auto-detect by extension (default) 71 | --inputFormat auto 72 | 73 | # JSON 74 | --inputFormat json 75 | 76 | # BSON 77 | --inputFormat bson 78 | 79 | # Message Pack 80 | --inputFormat msgpack 81 | 82 | # XML (removed in 2025.1.1) 83 | --inputFormat xml 84 | 85 | --inputFormattingOptions 86 | Additional options for specified format. 87 | 88 | This command supports :doc:`universal parameters `. 89 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_backup.rst: -------------------------------------------------------------------------------- 1 | Create Backup 2 | ============= 3 | 4 | | Backs up game data to a specified file. Saved data could be later used with :doc:`DATA RESTORE ` command. 5 | | Also this command can be used to convert game data into different format. 6 | 7 | - :ref:`CLI Installation ` 8 | - :ref:`Commands Reference ` 9 | - :doc:`Universal Parameters ` 10 | - :doc:`URL-based Input/Output ` 11 | 12 | --------------- 13 | Command 14 | --------------- 15 | 16 | .. code-block:: bash 17 | 18 | # local game data (windows) 19 | dotnet charon DATA BACKUP --dataBase "c:\my app\gamedata.json" --output "c:\my app\backup.msgpkg" --outputFormat msgpack 20 | 21 | # remote game data 22 | dotnet charon DATA BACKUP --dataBase "https://charon.live/view/data/My_Game/develop/" --output "./backup.msgpkg" --outputFormat msgpack --credentials "" 23 | 24 | --------------- 25 | Parameters 26 | --------------- 27 | 28 | --dataBase 29 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 30 | 31 | .. code-block:: bash 32 | 33 | # local file 34 | --dataBase "c:\my app\gamedata.json" 35 | 36 | # remote server 37 | --dataBase "https://charon.live/view/data/My_Game/develop/" 38 | 39 | --credentials 40 | The API key used to access remote server in case of *--dataBase* being URL. 41 | 42 | --output 43 | Path to a backup file. If the file exists, it will be overwritten. The directory must already exist. 44 | Alternatively, you can output to `Standard Error `_, 45 | `Standard Output `_, 46 | `/dev/null `_, or a :doc:`URL `. 47 | 48 | .. code-block:: bash 49 | 50 | # standart output (default) 51 | --output out 52 | --output con 53 | 54 | # standart error 55 | --output err 56 | 57 | # null device 58 | --output null 59 | 60 | # absolute path (windows) 61 | --output "c:\my app\backup.json" 62 | 63 | # absolute path (unix) 64 | --output "/user/data/backup.json" 65 | 66 | # relative path (universal) 67 | --output "./backup.json" 68 | 69 | # remote location (HTTP) 70 | --output "http://example.com/backup.json" 71 | 72 | # remote location with authentication (FTP) 73 | --output "ftp://user:password@example.com/backup.json" 74 | 75 | --outputFormat 76 | Format of backed up data. 77 | 78 | .. code-block:: bash 79 | 80 | # JSON (default) 81 | --outputFormat json 82 | 83 | # Message Pack 84 | --outputFormat msgpack 85 | 86 | --outputFormattingOptions 87 | Additional options for specified format. 88 | 89 | This command supports :doc:`universal parameters `. 90 | 91 | ------------------ 92 | Output 93 | ------------------ 94 | 95 | The back up data follows the general :doc:`game data structure <../game_data_structure>`. -------------------------------------------------------------------------------- /docs/advanced/commands/data_create_patch.rst: -------------------------------------------------------------------------------- 1 | Create Patch 2 | =========== 3 | 4 | Outputs the differences between two game datas as a file that can be used later to :doc:`DATA APPLYPATCH ` to another game data. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA CREATEPATCH --dataBase "c:\my app\gamedata.json" --input "c:\my app\gamedata_patch.json" --inputFormat json 19 | 20 | # remote game data 21 | dotnet charon DATA CREATEPATCH --dataBase "https://charon.live/view/data/My_Game/develop/" --input "./gamedata_patch.json" --inputFormat json --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase1 28 | Absolute or relative path to a first game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase1 "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase1 "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --dataBase2 39 | Absolute or relative path to a second game data. Use quotation marks if your path contains spaces. 40 | 41 | .. code-block:: bash 42 | 43 | # local file 44 | --dataBase2 "c:\my app\gamedata.json" 45 | 46 | # remote server 47 | --dataBase2 "https://charon.live/view/data/My_Game/develop/" 48 | 49 | --output 50 | Path to a patch file. If the file exists, it will be overwritten. The directory must already exist. 51 | Alternatively, you can output to `Standard Error `_, 52 | `Standard Output `_, 53 | `/dev/null `_, or a :doc:`URL `. 54 | 55 | .. code-block:: bash 56 | 57 | # standart output (default) 58 | --output out 59 | --output con 60 | 61 | # standart error 62 | --output err 63 | 64 | # null device 65 | --output null 66 | 67 | # absolute path (windows) 68 | --output "c:\my app\gamedata_patch.json" 69 | 70 | # absolute path (unix) 71 | --output /user/data/gamedata_patch.json 72 | 73 | # relative path (universal) 74 | --output "./gamedata_patch.json" 75 | 76 | # remote location (HTTP) 77 | --output "http://example.com/gamedata_patch.json" 78 | 79 | # remote location with authentication (FTP) 80 | --output "ftp://user:password@example.com/gamedata_patch.json" 81 | 82 | --outputFormat 83 | Format of exported data. 84 | 85 | .. code-block:: bash 86 | 87 | # JSON (default) 88 | --outputFormat json 89 | 90 | # BSON 91 | --outputFormat bson 92 | 93 | # Message Pack 94 | --outputFormat msgpack 95 | 96 | # XML (removed in 2025.1.1) 97 | --outputFormat xml 98 | 99 | 100 | --outputFormattingOptions 101 | Additional options for specified format. 102 | 103 | --credentials 104 | This parameter sets the API key used to access *BOTH* remote servers. 105 | If this is not suitable, consider :doc:`downloading ` the data locally and running this command on local files instead. 106 | 107 | This command supports :doc:`universal parameters `. -------------------------------------------------------------------------------- /docs/advanced/commands/data_delete.rst: -------------------------------------------------------------------------------- 1 | Delete Document 2 | =============== 3 | 4 | Deletes a document. For a bulk deletion use :doc:`DATA IMPORT ` command with ``--mode delete``. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA DELETE --dataBase "c:\my app\gamedata.json" --schema Item --id "Sword" 19 | 20 | # remote game data 21 | dotnet charon DATA DELETE --dataBase "https://charon.live/view/data/My_Game/develop/" --schema Item --id "Sword" --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --schema 42 | Name or identifier of the type (schema) of deleting document. 43 | 44 | .. code-block:: bash 45 | 46 | # name 47 | --schema Item 48 | 49 | # id 50 | --schema 55a4f32faca22e191098f3d9 51 | 52 | --id 53 | Identifier of deleting document. 54 | 55 | .. code-block:: bash 56 | 57 | # text 58 | --id Sword 59 | 60 | # number 61 | --id 101 62 | 63 | --output 64 | The path to a file where the *deleted document* should be placed. If the file exists, it will be overwritten. The directory must already exist. 65 | Alternatively, you can output to `Standard Error `_, 66 | `Standard Output `_, 67 | `/dev/null `_, or a :doc:`URL `. 68 | 69 | .. code-block:: bash 70 | 71 | # standart output 72 | --output out 73 | --output con 74 | 75 | # standart error 76 | --output err 77 | 78 | # null device (default) 79 | --output null 80 | 81 | # absolute path (windows) 82 | --output "c:\my app\deleted_item.json" 83 | 84 | # absolute path (unix) 85 | --output /user/data/deleted_item.json 86 | 87 | # relative path (universal) 88 | --output "./deleted_item.json" 89 | 90 | # remote location (HTTP) 91 | --output "http://example.com/deleted_item.json" 92 | 93 | # remote location with authentication (FTP) 94 | --output "ftp://user:password@example.com/deleted_item.json" 95 | 96 | --outputFormat 97 | Format for deleted document. 98 | 99 | .. code-block:: bash 100 | 101 | # JSON (default) 102 | --outputFormat json 103 | 104 | # BSON 105 | --outputFormat bson 106 | 107 | # Message Pack 108 | --outputFormat msgpack 109 | 110 | # XML (removed in 2025.1.1) 111 | --outputFormat xml 112 | 113 | --outputFormattingOptions 114 | Additional options for specified format. 115 | 116 | This command supports :doc:`universal parameters `. 117 | 118 | ------------------ 119 | Output 120 | ------------------ 121 | 122 | Outputs the deleted document in its state at the time of deletion. 123 | 124 | .. code-block:: json 125 | 126 | { 127 | "Id": "Sword" 128 | 129 | /* rest of properties of deleted document */ 130 | } 131 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_find.rst: -------------------------------------------------------------------------------- 1 | Find Document 2 | =============== 3 | 4 | Seaches for a document. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA FIND --dataBase "c:\my app\gamedata.json" --schema Character --id John 19 | 20 | # remote game data 21 | dotnet charon DATA FIND --dataBase "https://charon.live/view/data/My_Game/develop/" --schema Character --id John --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --schema 42 | Name or identifier of the type (schema) of document. 43 | 44 | .. code-block:: bash 45 | 46 | # name 47 | --schema Item 48 | 49 | # id 50 | --schema 55a4f32faca22e191098f3d9 51 | 52 | --id 53 | Identifier of document. 54 | 55 | .. code-block:: bash 56 | 57 | # text 58 | --id Sword 59 | 60 | # number 61 | --id 101 62 | 63 | --output 64 | Path to a found document file. If the file exists, it will be overwritten. The directory must already exist. 65 | Alternatively, you can output to `Standard Error `_, 66 | `Standard Output `_, 67 | `/dev/null `_, or a :doc:`URL `. 68 | 69 | .. code-block:: bash 70 | 71 | # standart output (default) 72 | --output out 73 | --output con 74 | 75 | # standart error 76 | --output err 77 | 78 | # null device 79 | --output null 80 | 81 | # absolute path (windows) 82 | --output "c:\my app\document.json" 83 | 84 | # absolute path (unix) 85 | --output /user/data/document.json 86 | 87 | # relative path (universal) 88 | --output "./document.json" 89 | 90 | # remote location (HTTP) 91 | --output "http://example.com/document.json" 92 | 93 | # remote location with authentication (FTP) 94 | --output "ftp://user:password@example.com/document.json" 95 | 96 | --outputFormat 97 | Format of exported data. 98 | 99 | .. code-block:: bash 100 | 101 | # JSON (default) 102 | --outputFormat json 103 | 104 | # BSON 105 | --outputFormat bson 106 | 107 | # Message Pack 108 | --outputFormat msgpack 109 | 110 | # XML (removed in 2025.1.1) 111 | --outputFormat xml 112 | 113 | --outputFormattingOptions 114 | Additional options for specified format. 115 | 116 | This command supports :doc:`universal parameters `. 117 | 118 | ------------------ 119 | Output 120 | ------------------ 121 | 122 | Outputs the found document. 123 | 124 | .. code-block:: json 125 | 126 | { 127 | "Id": "John" 128 | 129 | /* rest of properties of found document */ 130 | } 131 | 132 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_i18n_add_language.rst: -------------------------------------------------------------------------------- 1 | Add Translation Languages 2 | ========================= 3 | 4 | Add translation languages to specified game data. 5 | 6 | - :ref:`CLI Installation ` 7 | - :doc:`Universal Parameters ` 8 | - :ref:`Commands Reference ` 9 | 10 | --------------- 11 | Command 12 | --------------- 13 | 14 | .. code-block:: bash 15 | 16 | # local game data (windows) 17 | dotnet charon DATA I18N ADDLANGUAGE --dataBase "c:\my app\gamedata.json" --languages "es-ES" "en-GB" 18 | 19 | # remote game data 20 | dotnet charon DATA I18N ADDLANGUAGE --dataBase "https://charon.live/view/data/My_Game/develop/" --languages "es-ES" "en-GB" --credentials "" 21 | 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --languages 39 | The list of languages to add. Values are `language tags (BCP 47) separated by space. `_. 40 | 41 | This command supports :doc:`universal parameters `. -------------------------------------------------------------------------------- /docs/advanced/commands/data_i18n_export.rst: -------------------------------------------------------------------------------- 1 | Export Translated Data 2 | ========================= 3 | 4 | Export text that can be translated into a file. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA I18N EXPORT --dataBase "c:\my app\gamedata.json" --schemas Character --sourceLanguage en-US --targetLanguage fr --output "c:\my app\character_loc.xliff" --outputFormat xliff 19 | 20 | # remote game data 21 | dotnet charon DATA I18N EXPORT --dataBase "https://charon.live/view/data/My_Game/develop/" --schemas Character --sourceLanguage en-US --targetLanguage fr --output "./character_loc.xliff" --outputFormat xliff --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --schemas 42 | A list of types of documents (schemas) to export. By default all schemas *EXCEPT* metadata are exported. 43 | 44 | - Use space to separate multiple schemas. 45 | - You can use wildcards (*) at the beginning and end of names. 46 | - You can use identifiers in {} instead of names. 47 | - You can exclude certain names by using an exclamation mark (!) at the beginning of their names. 48 | 49 | .. code-block:: bash 50 | 51 | # schema name 52 | --schemas Character 53 | --schemas Character Item 54 | 55 | # all (default) 56 | --schemas * 57 | 58 | # masks 59 | --schemas Char* 60 | --schemas *Modifier 61 | --schemas *Mod* 62 | 63 | # schema id 64 | --schemas {18d4bf318f3c49688087dbed} 65 | 66 | # negation 67 | --schemas Char* !Character 68 | --schemas !*Item* 69 | 70 | # excluding system schemas (Schema, SchemaProperty, ProjectSettings) 71 | --schemas ![system] 72 | 73 | --sourceLanguage 74 | Source (original) language for translation. Value is `language tag (BCP 47) `_. 75 | 76 | Use :doc:`DATA I18N LANGUAGES ` to get list of used languages. 77 | 78 | .. code-block:: bash 79 | 80 | # it is used as in XLIFF 81 | --sourceLanguage en-US 82 | 83 | --targetLanguage 84 | Target language for translation. Value is `language tag (BCP 47) `_. 85 | 86 | .. code-block:: bash 87 | 88 | # it is used as in XLIFF 89 | --targetLanguage es-ES 90 | 91 | --output 92 | Path to a file to which data will be exported. If the file exists, it will be overwritten. The directory must already exist. 93 | Alternatively, you can output to `Standard Error `_, 94 | `Standard Output `_, 95 | `/dev/null `_, or a :doc:`URL `. 96 | 97 | .. code-block:: bash 98 | 99 | # standart output (default) 100 | --output out 101 | --output con 102 | 103 | # standart error 104 | --output err 105 | 106 | # null device 107 | --output null 108 | 109 | # absolute path (windows) 110 | --output "c:\my app\input.json" 111 | 112 | # absolute path (unix) 113 | --output /user/data/input.json 114 | 115 | # relative path (universal) 116 | --output "./input.json" 117 | 118 | # remote location (HTTP) 119 | --output "http://example.com/input.json" 120 | 121 | # remote location with authentication (FTP) 122 | --output "ftp://user:password@example.com/input.json" 123 | 124 | --outputFormat 125 | Format of exported data. 126 | 127 | .. code-block:: bash 128 | 129 | # XLIFF v2 (default) 130 | --outputFormat xliff 131 | --outputFormat xliff2 132 | 133 | # XLIFF v1 134 | --outputFormat xliff1 135 | 136 | # XSLX Spreadsheet 137 | --outputFormat xslx 138 | 139 | # JSON 140 | --outputFormat json 141 | 142 | 143 | --outputFormattingOptions 144 | Additional options for specified format. 145 | 146 | This command supports :doc:`universal parameters `. 147 | 148 | ------------------ 149 | Output 150 | ------------------ 151 | 152 | The exported data follows the general :doc:`game data structure <../game_data_structure>`, but omits `ToolsVersion`, `RevisionHash`, and `ChangeNumber` fields. -------------------------------------------------------------------------------- /docs/advanced/commands/data_i18n_languages.rst: -------------------------------------------------------------------------------- 1 | List Translation Languages 2 | ========================= 3 | 4 | Get a list of supported translation languages. Primary language always shows up first in the list. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA I18N LANGUAGES --dataBase "c:\my app\gamedata.json" --output out --outputFormat table 19 | 20 | # remote game data 21 | dotnet charon DATA I18N LANGUAGES --dataBase "https://charon.live/view/data/My_Game/develop/" --output out --outputFormat table --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --output 42 | Path to language list 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 :doc:`URL `. 43 | 44 | .. code-block:: bash 45 | 46 | # standart output (default) 47 | --output out 48 | --output con 49 | 50 | # standart error 51 | --output err 52 | 53 | # null device 54 | --output null 55 | 56 | # absolute path (windows) 57 | --output "c:\my app\input.json" 58 | 59 | # absolute path (unix) 60 | --output /user/data/input.json 61 | 62 | # relative path (universal) 63 | --output "./input.json" 64 | 65 | # remote location (HTTP) 66 | --output "http://example.com/input.json" 67 | 68 | # remote location with authentication (FTP) 69 | --output "ftp://user:password@example.com/input.json" 70 | 71 | --outputFormat 72 | Format of exported data. 73 | 74 | .. code-block:: bash 75 | 76 | # JSON (default) 77 | --outputFormat json 78 | 79 | #> [ 80 | #> "en-US", 81 | #> "es-ES", 82 | #> ] 83 | 84 | 85 | # Space separated list 86 | --outputFormat list 87 | 88 | #> en-US es-ES 89 | 90 | # New line (OS specific) separated list 91 | --outputFormat table 92 | 93 | #> en-US 94 | #> es-ES 95 | 96 | 97 | --outputFormattingOptions 98 | Additional options for specified format. 99 | 100 | This command supports :doc:`universal parameters `. 101 | 102 | 103 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_list.rst: -------------------------------------------------------------------------------- 1 | List Documents 2 | ============== 3 | 4 | Seaches for a documents. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA LIST --dataBase "c:\my app\gamedata.json" --schema Character 19 | 20 | # remote game data 21 | dotnet charon DATA LIST --dataBase "https://charon.live/view/data/My_Game/develop/" --schema Character --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --schema 42 | Name or identifier of the type (schema) of document. 43 | 44 | .. code-block:: bash 45 | 46 | # name 47 | --schema Item 48 | 49 | # id 50 | --schema 55a4f32faca22e191098f3d9 51 | 52 | --filters 53 | Document filter expressions. 54 | 55 | .. code-block:: bash 56 | 57 | # patterns 58 | --filters [ ...] 59 | 60 | # single expression 61 | --filters Id > 10 62 | --filters Name like "Zombie" 63 | 64 | # multiple expressions 65 | --filters Id > 10 Name like "Zombie" 66 | 67 | # greater than 68 | --filters Id > 0 69 | --filters Id greaterThan 0 70 | 71 | 72 | # greater than or equal 73 | --filters Id >= 0 74 | --filters Id greaterThanOrEqual 0 75 | 76 | 77 | # less than 78 | --filters Id < 0 79 | --filters Id lessThan 0 80 | 81 | # less than or equal 82 | --filters Id <= 0 83 | --filters Id LessThanOrEqual 0 84 | 85 | # equal 86 | --filters Id = 0 87 | --filters Id == 0 88 | --filters Id equal 0 89 | 90 | # not equal 91 | --filters Id <> 0 92 | --filters Id != 0 93 | --filters Id notEqual 0 94 | 95 | # like - is used to search for specific patterns in a field, allowing for partial matches. 96 | --filters Name like "Zombie" 97 | 98 | --sorters 99 | Document sort expressions. 100 | 101 | .. code-block:: bash 102 | 103 | # patterns 104 | --sorters ASC|DESC [ ASC|DESC ...] 105 | 106 | # ascending 107 | --sorters Name ASC 108 | 109 | # descending 110 | --sorters Name DESC 111 | 112 | --path 113 | Embeddance path filter. Could be used to get only embedded documents. 114 | 115 | .. code-block:: bash 116 | 117 | # any path 118 | --path * 119 | 120 | # root documents (default) 121 | --path "" 122 | 123 | # in 'Item' property 124 | --path /Item 125 | 126 | --skip 127 | Number of found documents to skip. 128 | 129 | .. code-block:: bash 130 | 131 | # skip first ten documents after applying --filter and --sort 132 | --skip 10 133 | 134 | --take 135 | Max amount to documents return. 136 | 137 | .. code-block:: bash 138 | 139 | # limit to first 100 documents after --skip 140 | --take 100 141 | 142 | --output 143 | Path to a found document file. If the file exists, it will be overwritten. The directory must already exist. 144 | Alternatively, you can output to `Standard Error `_, 145 | `Standard Output `_, 146 | `/dev/null `_, or a :doc:`URL `. 147 | 148 | .. code-block:: bash 149 | 150 | # standart output (default) 151 | --output out 152 | --output con 153 | 154 | # standart error 155 | --output err 156 | 157 | # null device 158 | --output null 159 | 160 | # absolute path (windows) 161 | --output "c:\my app\document.json" 162 | 163 | # absolute path (unix) 164 | --output /user/data/document.json 165 | 166 | # relative path (universal) 167 | --output "./document.json" 168 | 169 | # remote location (HTTP) 170 | --output "http://example.com/document.json" 171 | 172 | # remote location with authentication (FTP) 173 | --output "ftp://user:password@example.com/document.json" 174 | 175 | --outputFormat 176 | Format of exported data. 177 | 178 | .. code-block:: bash 179 | 180 | # JSON (default) 181 | --outputFormat json 182 | 183 | # BSON 184 | --outputFormat bson 185 | 186 | # Message Pack 187 | --outputFormat msgpack 188 | 189 | # XML (removed in 2025.1.1) 190 | --outputFormat xml 191 | 192 | --outputFormattingOptions 193 | Additional options for specified format. 194 | 195 | This command supports :doc:`universal parameters `. 196 | 197 | ------------------ 198 | Output 199 | ------------------ 200 | 201 | The exported data follows the general :doc:`game data structure <../game_data_structure>`, but omits `ToolsVersion`, `RevisionHash`, and `ChangeNumber`. 202 | 203 | .. code-block:: json 204 | 205 | { 206 | "Collections": 207 | { 208 | "Character": 209 | [ 210 | { 211 | "Id": "Knight" 212 | 213 | /* rest of properties of document */ 214 | }, 215 | { 216 | "Id": "Templar" 217 | 218 | /* rest of properties of document */ 219 | }, 220 | // ... 221 | ] 222 | } 223 | } 224 | 225 | -------------------------------------------------------------------------------- /docs/advanced/commands/data_restore.rst: -------------------------------------------------------------------------------- 1 | Restore from Backup 2 | =================== 3 | 4 | Restores game data from a file created by :doc:`DATA BACKUP ` command. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon DATA RESTORE --dataBase "c:\my app\gamedata.json" --input "c:\my app\backup.msgpkg" --inputFormat msgpack 19 | 20 | # remote game data 21 | dotnet charon DATA RESTORE --dataBase "https://charon.live/view/data/My_Game/develop/" --input "./backup.msgpkg" --inputFormat msgpack --credentials "" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | # remote server 36 | --dataBase "https://charon.live/view/data/My_Game/develop/" 37 | 38 | --credentials 39 | The API key used to access remote server in case of *--dataBase* being URL. 40 | 41 | --input 42 | Path to a backup file. Alternatively, you can use `Standart Input `_ or :doc:`URL `. 43 | 44 | .. code-block:: bash 45 | 46 | # standart input (default) 47 | --input in 48 | --input con 49 | 50 | # absolute path (windows) 51 | --input "c:\my app\backup.json" 52 | 53 | # absolute path (unix) 54 | --input "/user/data/backup.json" 55 | 56 | # relative path (universal) 57 | --input "./backup.json" 58 | 59 | # remote location (HTTP) 60 | --input "http://example.com/backup.json" 61 | 62 | # remote location with authentication (FTP) 63 | --input "ftp://user:password@example.com/backup.json" 64 | 65 | --inputFormat 66 | Format of imported data. 67 | 68 | .. code-block:: bash 69 | 70 | # Auto-detect by extension (default) 71 | --inputFormat auto 72 | 73 | # JSON 74 | --inputFormat json 75 | 76 | # Message Pack 77 | --inputFormat msgpack 78 | 79 | --inputFormattingOptions 80 | Additional options for specified format. 81 | 82 | This command supports :doc:`universal parameters `. 83 | -------------------------------------------------------------------------------- /docs/advanced/commands/generate_templates.rst: -------------------------------------------------------------------------------- 1 | Export Code Generation Templates 2 | ======================== 3 | 4 | Exports `T4 `_ code generation templates to a specified directory. 5 | These templates can be used with Visual Studio, Rider, Visual Studio Code with plugin, ``dotnet`` `tool `_ or other tools to generate source code. 6 | 7 | - :ref:`CLI Installation ` 8 | - :ref:`Commands Reference ` 9 | - :doc:`Universal Parameters ` 10 | - :doc:`URL-based Input/Output ` 11 | 12 | --------------- 13 | Command 14 | --------------- 15 | 16 | .. code-block:: bash 17 | 18 | # Windows 19 | dotnet charon GENERATE TEMPLATES --outputDirectory "c:\templates" 20 | 21 | 22 | --------------- 23 | Parameters 24 | --------------- 25 | 26 | --outputDirectory 27 | Specifies the path where the templates should be written. It can be either an absolute or relative path to a directory. The specified directory must already be present. 28 | 29 | .. code-block:: bash 30 | 31 | # Windows 32 | --outputDirectory "c:\templates" 33 | 34 | # Linux or OSX 35 | --outputDirectory "~/templates" 36 | 37 | # Relative path 38 | --outputDirectory "./templates" 39 | -------------------------------------------------------------------------------- /docs/advanced/commands/generate_text.rst: -------------------------------------------------------------------------------- 1 | Generate Text from Templates (Obsolete) 2 | ======================================= 3 | 4 | | Generates text from T4 templates into output directory. 5 | 6 | .. warning:: 7 | This command was removed since 2025.1.1 version. 8 | It is recommended to use an IDE or open-source alternatives for generating text with T4 templates. 9 | See: `dotnet-t4 `_ 10 | 11 | 12 | | See :doc:`GENERATE TEMPLATES ` to get actual T4 templates. 13 | 14 | - :ref:`CLI Installation ` 15 | - :ref:`Commands Reference ` -------------------------------------------------------------------------------- /docs/advanced/commands/init.rst: -------------------------------------------------------------------------------- 1 | Initialize Game Data 2 | ==================== 3 | 4 | Initializes an empty or missing file with initial data. Path to game data should be local file system's file. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | 9 | --------------- 10 | Command 11 | --------------- 12 | 13 | .. code-block:: bash 14 | 15 | # full path (windows) 16 | dotnet charon INIT "c:\my app\gamedata.gdjs" 17 | 18 | # full path (linux) 19 | dotnet charon INIT "/var/mygame/gamedata.json" 20 | 21 | # relative path 22 | dotnet charon INIT mygame/gamedata.json 23 | 24 | --------------- 25 | Parameters 26 | --------------- 27 | 28 | --fileName 29 | Absolute or relative path to game data file. Use quotation marks if your path contains spaces. 30 | 31 | .. code-block:: bash 32 | 33 | # local file 34 | --fileName "c:\my app\gamedata.json" 35 | -------------------------------------------------------------------------------- /docs/advanced/commands/remote_input_output.rst: -------------------------------------------------------------------------------- 1 | URL input/output parameters 2 | =========================== 3 | 4 | Some command accept `URL `_ as input/output parameter. 5 | 6 | Supported URL Schemes 7 | --------------------- 8 | 9 | +---------+----------------------------+-----------------------------------------------------+ 10 | | Scheme | Input parameter | Output parameter | 11 | +=========+============================+=====================================================+ 12 | | HTTP[S] | A GET request will be sent | A POST request with body containing output will be | 13 | | | | sent | 14 | +---------+----------------------------+-----------------------------------------------------+ 15 | | FTP(S) | A RETR command will be sent| A STOR command with output content will be sent | 16 | +---------+----------------------------+-----------------------------------------------------+ 17 | | FILE | File will be read | File will be written | 18 | +---------+----------------------------+-----------------------------------------------------+ 19 | 20 | Authentication 21 | -------------- 22 | Authentication data could be passed in *user* part of `URL `_. 23 | More advanced authentication schemes are not supported. 24 | 25 | Examples 26 | -------- 27 | 28 | .. code-block:: bash 29 | 30 | # publish data to FTP 31 | dotnet charon DATA EXPORT 32 | --dataBase "https://charon.live/view/data/My_Game/develop/dashboard" 33 | --output "ftp://user:password@example.com/public/gamedata.json" 34 | --mode publication 35 | --outputFormat json 36 | --credentials "" 37 | 38 | # import localization from remote HTTP server 39 | dotnet charon DATA I18N IMPORT 40 | --dataBase "file:///c:/my app/gamedata.json" 41 | --input "https://example.com/translated/gamedata.xliff" 42 | --inputFormat xliff 43 | 44 | # print languages for game data in local file 45 | dotnet charon DATA I18N LANGUAGES --dataBase "file:///c:/my app/gamedata.json" 46 | 47 | # print languages for game data in local file relative to current working directory 48 | dotnet charon DATA I18N LANGUAGES --dataBase "file:///./gamedata.json" 49 | 50 | # print languages for game data at remote server using API Key 51 | export CHARON_API_KEY=87758CC0D7C745D0948F2A8AFE61BC81 52 | dotnet charon DATA I18N LANGUAGES --dataBase "https://charon.live/view/data/My_Game/develop/dashboard" 53 | 54 | 55 | -------------------------------------------------------------------------------- /docs/advanced/commands/serve.rst: -------------------------------------------------------------------------------- 1 | Start in Standalone Mode 2 | ======================== 3 | 4 | Starts Charon in standalone mode for specified game data. Path to game data could be local file system's file or remote server address. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | - :doc:`Universal Parameters ` 9 | - :doc:`URL-based Input/Output ` 10 | 11 | --------------- 12 | Command 13 | --------------- 14 | 15 | .. code-block:: bash 16 | 17 | # local game data (windows) 18 | dotnet charon SERVER START --dataBase "c:\my app\gamedata.json" --port 8080 --launchDefaultBrowser 19 | 20 | # shortcut version 21 | dotnet charon "c:\my app\gamedata.json" 22 | 23 | --------------- 24 | Parameters 25 | --------------- 26 | 27 | --dataBase 28 | Absolute or relative path to game data. Use quotation marks if your path contains spaces. 29 | 30 | .. code-block:: bash 31 | 32 | # local file 33 | --dataBase "c:\my app\gamedata.json" 34 | 35 | --port 36 | Number of an `IP port `_ (1-65535) to be used to listen for browser based UI. 37 | 38 | .. code-block:: bash 39 | --port 8080 40 | 41 | --launchDefaultBrowser 42 | Set this flag to open system-default browser on successful start. 43 | 44 | --resetPreferences 45 | Set this flag to reset UI preferences on successful start. 46 | 47 | This command supports :doc:`universal parameters `. 48 | -------------------------------------------------------------------------------- /docs/advanced/commands/universal_parameters.rst: -------------------------------------------------------------------------------- 1 | Universal parameters 2 | ==================== 3 | 4 | All commands accept universal parameters and environment variables. 5 | 6 | --verbose 7 | Set this flag to get additional diagnostic information in logs. 8 | 9 | --log 10 | Add additional file logging to the existing logging configuration from ``appsettings.json``. 11 | 12 | .. code-block:: bash 13 | 14 | --log "./logs/charon.log" 15 | 16 | --log out 17 | Add additional terminal (`standard output `_) logging to the existing logging configuration from ``appsettings.json``. 18 | 19 | .. code-block:: bash 20 | 21 | --log out 22 | # or 23 | --log con 24 | 25 | --pause 26 | Wait for user prompt before the application exits. 27 | 28 | Environment variables 29 | ===================== 30 | 31 | In addition to the standard configuration redefinition `mechanism `_ 32 | using environment variables, the following environment variables are also supported. 33 | 34 | CHARON_API_KEY 35 | The :doc:`API key <../../online/cli_access_to_your_project>` which is used to access the remote server. This environment variable is usually used in 36 | conjunction with ``--dataBase``, which points to a remote server. 37 | 38 | .. code-block:: bash 39 | 40 | # Windows 41 | set CHARON_API_KEY=87758CC0D7C745D0948F2A8AFE61BC81 42 | 43 | # OSX or Linux 44 | export CHARON_API_KEY=87758CC0D7C745D0948F2A8AFE61BC81 45 | -------------------------------------------------------------------------------- /docs/advanced/commands/version.rst: -------------------------------------------------------------------------------- 1 | Get Charon Version 2 | ================== 3 | 4 | Gets version of ``dotnet charon`` application. 5 | 6 | - :ref:`CLI Installation ` 7 | - :ref:`Commands Reference ` 8 | 9 | --------------- 10 | Command 11 | --------------- 12 | 13 | .. code-block:: bash 14 | 15 | # Windows, Linux or OSX 16 | dotnet charon VERSION 17 | #> 2023.2.3-alpha 18 | 19 | --------------- 20 | Parameters 21 | --------------- 22 | 23 | This command supports :doc:`universal parameters `. 24 | -------------------------------------------------------------------------------- /docs/advanced/extensions/implementing_property_editor.rst: -------------------------------------------------------------------------------- 1 | Implementing ``CharonPropertyEditorElement`` 2 | -------------------------------------------- 3 | 4 | Each custom property editor must implement the ``CharonPropertyEditorElement`` interface from the `charon-extensions `_ package: 5 | 6 | .. code-block:: typescript 7 | 8 | export declare interface CharonPropertyEditorElement { 9 | valueControl: ValueControl; 10 | } 11 | 12 | When the editor is rendered, Charon sets ``valueControl`` to allow your component to: 13 | 14 | - Subscribe to input value changes. 15 | - Update the current value. 16 | - Access schema metadata. 17 | - Add custom validation. 18 | - Respond to focus events. 19 | 20 | Understanding ``ValueControl`` 21 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22 | 23 | The ``ValueControl`` interface loosely mirrors Angular’s `AbstractControl `_. Here's a simplified definition: 24 | 25 | .. code-block:: typescript 26 | 27 | export declare interface ValueControl { 28 | readonly schemaProperty: SchemaProperty; 29 | 30 | readonly valueChanges: ObservableLike; 31 | readonly value: TValue; 32 | 33 | setValue(value: TValue, options?: ControlEventEmitOptions): void; 34 | 35 | registerDoFocus(fn: (options?: FocusOptions) => void, targetName?: string): TeardownLogic; 36 | 37 | readonly errors: Object | null; 38 | 39 | addValidators(validators: ValueValidatorFn | ValueValidatorFn[]): void; 40 | removeValidators(validators: ValueValidatorFn | ValueValidatorFn[]): void; 41 | hasValidator(validator: ValueValidatorFn): boolean; 42 | } 43 | 44 | Reacting to Value Changes 45 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 46 | 47 | When your editor receives the ``valueControl``, subscribe to ``valueChanges``: 48 | 49 | .. code-block:: tsx 50 | 51 | useEffect(() => { 52 | const subscription = valueControl.valueChanges.subscribe(value => { 53 | setLocalValue(value); // Update local state 54 | }); 55 | 56 | return () => subscription.unsubscribe(); // Cleanup on unmount 57 | }, [valueControl]); 58 | 59 | When the user edits the field, call: 60 | 61 | .. code-block:: tsx 62 | 63 | valueControl.setValue(newValue); // it will trigger `valueControl.valueChanges` even if values are same (!) 64 | 65 | The format and type of the value are described in ``valueControl.schemaProperty``. 66 | 67 | Handling Focus Events 68 | ^^^^^^^^^^^^^^^^^^^^^ 69 | 70 | Charon can request that your editor focuses the first interactive element. Use ``registerDoFocus``: 71 | 72 | .. code-block:: tsx 73 | 74 | useEffect(() => { 75 | const teardown = valueControl.registerDoFocus(() => { 76 | inputRef.current?.focus(); 77 | }); 78 | 79 | return () => teardown(); // Unregister on unmount or control change 80 | }, [valueControl]); 81 | 82 | Providing Custom Validators 83 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 84 | 85 | To enable custom validation: 86 | 87 | 1. Register validators when ``valueControl`` is assigned. 88 | 2. Clean them up when your component is destroyed or ``valueControl`` changes. 89 | 90 | Example: 91 | 92 | .. code-block:: tsx 93 | 94 | useEffect(() => { 95 | const validateValue = (control: ValueControl): Object | null => { 96 | if (isValidColor(control.value)) { 97 | return null; 98 | } 99 | return { 100 | ERROR_CUSTOM: 'Invalid value for color in #XXXXXX format.' 101 | }; 102 | }; 103 | 104 | valueControl.addValidators(validateValue); 105 | return () => valueControl.removeValidators(validateValue); 106 | }, [valueControl]); 107 | -------------------------------------------------------------------------------- /docs/advanced/extensions/overview.rst: -------------------------------------------------------------------------------- 1 | UI Extensions 2 | ============= 3 | 4 | Charon supports a powerful plugin model through **extensions**, which allow developers to create custom field and document editors that integrate with the application. These extensions are built using **Web Components** and packaged as **NPM modules** for easy distribution and reuse. 5 | 6 | What Is a Charon Extension? 7 | --------------------------- 8 | 9 | A **Charon extension** is an external package that provides one or more custom UI components (editors) used inside the document form. 10 | 11 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/editor_custom_editor.png 12 | :width: 800 13 | :alt: Form with custom editor 14 | 15 | 16 | Each extension is: 17 | 18 | - A **Web Component** implementing a specific interface. 19 | - Packaged as a standard **NPM module**. 20 | - Discoverable by Charon at runtime (via local ``.tgz`` or a public NPM registry). 21 | - Described with metadata in ``package.json`` under the ``config.customEditors`` section. 22 | 23 | What Is a Web Component? 24 | ------------------------ 25 | 26 | A **Web Component** is a browser-native way to define reusable UI elements that are: 27 | 28 | - **Encapsulated**: HTML, CSS, and JS are scoped to the component. 29 | - **Self-contained**: No dependencies on the application’s framework. 30 | - **Reusable**: Can be shared across projects regardless of frontend tech (React, Angular, Vue, etc.). 31 | 32 | This isolation is essential for Charon, which must load unknown user-defined components without conflict or side effects. 33 | 34 | What Is an NPM Package? 35 | ----------------------- 36 | 37 | An **NPM package** is a collection of files published to the `npm registry `_ or used locally. It contains: 38 | 39 | - JavaScript bundles 40 | - Stylesheets (optional) 41 | - Metadata (``package.json``) 42 | - Documentation or type definitions 43 | 44 | In Charon, an extension is published as an NPM package (or ``.tgz`` archive) and loaded dynamically at runtime. 45 | 46 | Typical NPM Package Structure 47 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 48 | 49 | A Charon extension NPM package usually contains: 50 | 51 | .. code-block:: 52 | 53 | dist/ 54 | ├── index.js # Compiled JS bundle that registers the component 55 | ├── assets/ 56 | │ └── index.css # Optional styles 57 | ├── package.json # Includes Charon metadata and schema reference 58 | └── *.tgz # (optional) Published archive 59 | 60 | Example ``package.json`` metadata: 61 | 62 | .. code-block:: json 63 | 64 | "config": { 65 | "customEditors": [ 66 | { 67 | "id": "ext-logical-toggle", 68 | "selector": "ext-logical-toggle-editor", 69 | "name": "Logical Toggle", 70 | "type": ["Property", "Grid"], 71 | "dataTypes": ["Logical"] 72 | } 73 | ] 74 | } 75 | 76 | Gettings Started 77 | ---------------- 78 | 79 | - :doc:`Creating a Custom Editor with React ` 80 | - :doc:`Creating a Custom Editor with Angular ` 81 | - :doc:`Implementing Custom Property Editor Interface ` 82 | 83 | Publication and Consumption 84 | --------------------------- 85 | 86 | After you implement the extension interface and build the UI logic to display and edit the value, you need to create a production build of your package and publish it either locally or to the NPM registry. 87 | 88 | To publish locally: 89 | 90 | .. code-block:: bash 91 | 92 | npm pack 93 | 94 | This creates a ``.tgz`` archive in your ``dist`` directory that can be manually placed in Charon’s extension folder for testing. 95 | 96 | To `publish `_ publicly: 97 | 98 | .. code-block:: bash 99 | 100 | npm publish 101 | 102 | Make sure your ``package.json`` contains all required metadata and the ``"private": true`` flag is removed. 103 | 104 | Once published, the extension package can be added through the ``Project Settings → Extensions`` tab in Charon. Enter the NPM package name and, optionally, specify a version. If the version is omitted, the latest published version will be used. 105 | 106 | The list of enabled extensions is saved inside your Charon data file, making it automatically available to all users working on that file. 107 | 108 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/project_settings_extensions.png 109 | :width: 800 110 | :alt: Project Settings Extensions 111 | 112 | .. note:: 113 | 114 | Locally installed extensions (via ``.tgz`` files) are intended only for development and debugging. They are available **only on your machine** and will not be shared with other users. 115 | 116 | See Also 117 | -------- 118 | 119 | - :doc:`Creating a Custom Editor with React ` 120 | - :doc:`Creating a Custom Editor with Angular ` 121 | - `Example Projects (GitHub) `_ 122 | 123 | -------------------------------------------------------------------------------- /docs/advanced/internationalization.rst: -------------------------------------------------------------------------------- 1 | =========================== 2 | Internationalization (i18n) 3 | =========================== 4 | 5 | Charon supports localization by enabling text data to be stored in multiple languages using the :doc:`Localized Text <../gamedata/datatypes/all/localized_text>` data type. This allows game data to be exported for translation, modified externally, and imported back after localization. 6 | 7 | Supported export formats include `XLSX `_, `XLIFF `_ (XML Localization Interchange File Format) and `JSON `_. These formats are suitable for translation workflows involving external tools or localization teams. 8 | 9 | Overview 10 | ======== 11 | 12 | Localization workflows in Charon rely on identifying fields of type :doc:`Localized Text <../gamedata/datatypes/all/localized_text>` and processing them through either spreadsheet or industry-standard interchange formats. Translated data can then be re-integrated using import commands. 13 | 14 | Common use cases include: 15 | 16 | - Managing multi-language game content. 17 | - Sending text data to third-party localization vendors. 18 | - Automating translation pipelines with CLI tools. 19 | 20 | Supported Languages 21 | =================== 22 | 23 | Translation languages are defined in the **Project Settings**. To view the configured languages via the CLI, run: 24 | 25 | .. code-block:: bash 26 | 27 | dotnet charon DATA I18N LANGUAGES --dataBase gamedata.json 28 | 29 | Exporting Translatable Text 30 | =========================== 31 | 32 | Charon provides two primary formats for exporting localizable content: XLSX and XLIFF. Exporting can be done via the graphical interface or command-line interface. 33 | 34 | XLSX Export (Spreadsheet) 35 | ------------------------- 36 | 37 | The following example exports all translatable text to an Excel spreadsheet: 38 | 39 | .. code-block:: bash 40 | 41 | dotnet charon DATA EXPORT --dataBase "gamedata.json" --properties [LocalizedText] --output "text_all_languages.xlsx" --outputFormat xlsx 42 | 43 | Key parameters: 44 | 45 | - ``--properties [LocalizedText]``: Filters exported data to include only `LocalizedText` fields. 46 | - ``--languages``: (Optional) Specifies which languages to include in the export. 47 | 48 | .. note:: 49 | The exported spreadsheet may contain additional metadata columns that are required for correct import. 50 | 51 | XLIFF Export (Industry Standard) 52 | -------------------------------- 53 | 54 | To export translation data in XLIFF format: 55 | 56 | .. code-block:: bash 57 | 58 | dotnet charon DATA I18N EXPORT --dataBase "gamedata.json" --sourceLanguage en --targetLanguage fr --output "en_fr_texts.xliff" --outputFormat xliff 59 | 60 | Key parameters: 61 | 62 | - ``--sourceLanguage``: Language of the original text. 63 | - ``--targetLanguage``: Language to which the content will be translated. 64 | - ``--outputFormat``: Format of the exported file. Supported values include `xliff`, `xliff1`, and `xliff2`. 65 | 66 | Importing Translated Data 67 | ========================== 68 | 69 | After translation, the modified data can be imported back into the project. Both XLSX and XLIFF formats are supported. 70 | 71 | XLSX Import 72 | ----------- 73 | 74 | To import translated spreadsheet data: 75 | 76 | .. code-block:: bash 77 | 78 | dotnet charon DATA IMPORT --dataBase "gamedata.json" --input "text_all_languages.xlsx" --inputFormat xlsx --mode safeUpdate 79 | 80 | Key parameters: 81 | 82 | - ``--inputFormat xlsx``: Indicates the input file format. 83 | - ``--mode safeUpdate``: Ensures only existing fields are updated, without creating or deleting data. 84 | 85 | XLIFF Import 86 | ------------ 87 | 88 | To import translated XLIFF content: 89 | 90 | .. code-block:: bash 91 | 92 | dotnet charon DATA I18N IMPORT --dataBase "gamedata.json" --input "en_fr_texts.xliff" 93 | 94 | Best Practices 95 | ============== 96 | 97 | - Use **XLSX** when working with translators familiar with spreadsheet tools. 98 | - Use **XLIFF** for integration with professional translation software or localization platforms. 99 | - Validate the translated data with a **dry run** before importing changes into production data. 100 | 101 | Unsupported Formats 102 | =================== 103 | 104 | While Charon may accept other serialization formats (e.g., BSON, MsgPack), compatibility for internationalization workflows is only guaranteed for XLSX, XLIFF and JSON. 105 | 106 | Additional Resources 107 | ==================== 108 | 109 | - :doc:`DATA EXPORT ` 110 | - :doc:`DATA IMPORT ` 111 | - :doc:`DATA I18N EXPORT ` 112 | - :doc:`DATA I18N IMPORT ` 113 | - :doc:`DATA I18N LANGUAGES ` 114 | -------------------------------------------------------------------------------- /docs/advanced/logs.rst: -------------------------------------------------------------------------------- 1 | Working with Logs 2 | ============== 3 | 4 | Charon creates a log files with various messages that may be useful for troubleshooting and debugging. 5 | 6 | Unity Plugin 7 | Log files are saved to ``/Library/Charon/logs/``. 8 | 9 | Unreal Engine Plugin 10 | Log files are saved to ``/Intermediate/Charon/logs/``. 11 | 12 | CLI and Standalone 13 | Log files are saved to: 14 | - Windows: ``C:/ProgramData/Charon/logs/``. 15 | - MacOS: ``/Library/Application Support/Charon/logs`` 16 | - Linux: ``/usr/share/Charon/logs`` 17 | 18 | Note: Make sure to replace ```` and ```` with the actual directories on your system. 19 | 20 | Logging Levels 21 | -------------- 22 | 23 | Normally only the most important events are logged. 24 | If you have trouble identifying an issue, you might want to change log 25 | to *verbose*. This way more information is included in logs. 26 | 27 | Unity Plugin 28 | In menu select ``Tools → Charon → Troubleshooting → Verbose Logs``. 29 | 30 | CLI and Standalone 31 | Launch with ``--verbose`` parameter. 32 | 33 | Then repeat the action that causes the bug (or the one you want analyzed anyway) and check log file again. 34 | 35 | CLI Example: 36 | 37 | .. code-block:: bash 38 | 39 | dotnet charon SERVER START ./gamedata.json --launchDefaultBrowser --verbose 40 | 41 | -------------------------------------------------------------------------------- /docs/advanced/reset_preferences.rst: -------------------------------------------------------------------------------- 1 | Resetting UI Preferences 2 | ======================== 3 | 4 | If for some reason editor behaves erratically (grids aren't displayed correctly or aren't displayed at all), you can restore default UI settings. 5 | 6 | Unity plugin 7 | Select in menu ``Tools → Charon → Troubleshooting → Reset Preferences``. 8 | CLI and Standalone 9 | Launch with ``--resetPreferences.`` parameter. 10 | Web 11 | Use the ``Preferences`` profile tab `` → Profile → Preferences``. 12 | 13 | CLI Example: 14 | 15 | .. code-block:: bash 16 | 17 | dotnet charon SERVER START ./gamedata.json --launchDefaultBrowser --resetPreferences 18 | 19 | -------------------------------------------------------------------------------- /docs/assets/cover_github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/cover_github.png -------------------------------------------------------------------------------- /docs/assets/dashboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/dashboard.png -------------------------------------------------------------------------------- /docs/assets/document_collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/document_collection.png -------------------------------------------------------------------------------- /docs/assets/document_form.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/document_form.png -------------------------------------------------------------------------------- /docs/assets/documents_import.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/documents_import.png -------------------------------------------------------------------------------- /docs/assets/editor_custom_editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/editor_custom_editor.png -------------------------------------------------------------------------------- /docs/assets/editor_screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/editor_screenshot.png -------------------------------------------------------------------------------- /docs/assets/how_it_works.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/how_it_works.png -------------------------------------------------------------------------------- /docs/assets/project_settings_extensions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/project_settings_extensions.png -------------------------------------------------------------------------------- /docs/assets/schema_designer_select_editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/schema_designer_select_editor.png -------------------------------------------------------------------------------- /docs/assets/schema_designer_select_extension_editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/schema_designer_select_extension_editor.png -------------------------------------------------------------------------------- /docs/assets/ue_document_reference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/ue_document_reference.png -------------------------------------------------------------------------------- /docs/assets/ue_editor_screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/ue_editor_screenshot.png -------------------------------------------------------------------------------- /docs/assets/ue_plugin_assets.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/ue_plugin_assets.png -------------------------------------------------------------------------------- /docs/assets/unity_document_reference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/unity_document_reference.png -------------------------------------------------------------------------------- /docs/assets/unity_edit_gamedata.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/unity_edit_gamedata.png -------------------------------------------------------------------------------- /docs/assets/unity_logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 17 | 19 | 20 | 22 | image/svg+xml 23 | 25 | 26 | 27 | 28 | 30 | 50 | 55 | 60 | 61 | -------------------------------------------------------------------------------- /docs/assets/unity_migrate_window.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/unity_migrate_window.png -------------------------------------------------------------------------------- /docs/assets/unity_plugin_asset_inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/unity_plugin_asset_inspector.png -------------------------------------------------------------------------------- /docs/assets/unity_plugin_assets.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/assets/unity_plugin_assets.png -------------------------------------------------------------------------------- /docs/assets/unreal_engine_logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 18 | 20 | 21 | 23 | image/svg+xml 24 | 26 | 27 | 28 | 29 | 31 | 51 | 57 | 62 | 63 | -------------------------------------------------------------------------------- /docs/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/favicon.ico -------------------------------------------------------------------------------- /docs/gamedata/basics.rst: -------------------------------------------------------------------------------- 1 | Basic Navigation and User Interface Overview 2 | ======== 3 | 4 | The UI consists of a left-side menu displaying all schemas of the game data, a middle working area with a dashboard/document list or document form, and a headline on the top with the project name and settings button. Depending on the installation, the UI may also include a user menu. 5 | 6 | Dashboard 7 | --------- 8 | 9 | The dashboard is a central hub in the game data's user interface that provides quick access to frequently used features. It includes quick action buttons, such as creating a new schema, export, import, as well as a list of recently visited documents. 10 | Additionally, in the case of a web application, the dashboard may display the presence of online members who are currently working in the same project. 11 | 12 | Document Collection 13 | ------------------- 14 | The document collection page is place where user can view a list of all the documents of a specified schema. This page allows users to filter, sort, and customize the list to their liking, making it easier to find the specific document they need. 15 | 16 | Document Form 17 | ------------- 18 | The document form page provides a specific edit form for a selected document. Here, users can view, edit, and save their game data documents in a structured and organized manner. The form allows users to input data into fields that correspond to the schema's properties. The document form page provides a user-friendly interface for updating and modifying game data. 19 | 20 | See also 21 | -------- 22 | 23 | - :doc:`Creating Document Type (Schema) ` 24 | - :doc:`Filling Documents ` 25 | - :doc:`Publishing Game Data ` 26 | - :doc:`Generating Source Code ` 27 | -------------------------------------------------------------------------------- /docs/gamedata/creating_schema.rst: -------------------------------------------------------------------------------- 1 | Creating Document Type (Schema) 2 | =============================== 3 | 4 | Schema 5 | ------ 6 | 7 | Schema is essential for organizing and defining game data in a structured framework. In the context of game data modeling, a schema serves as a blueprint or template that establishes the structure and properties of a particular type of data entity in a game. It defines the columns or fields that represent the various attributes of the entity, similar to how a table has columns or a spreadsheet has cells. 8 | 9 | .. figure:: ./enemy_schema_example.png 10 | 11 | Benefits of Structured Data 12 | --------------------------- 13 | 14 | Data Organization 15 | ^^^^^^^^^^^^^^^^^ 16 | 17 | The organization of game data into logical entities and attributes is facilitated by the schema. This blueprint or template defines the structure, properties, and relationships of different entities and attributes within the game data, ensuring efficient storage, retrieval, and management. 18 | 19 | Data Validation 20 | ^^^^^^^^^^^^^^^ 21 | 22 | The integrity and adherence to predefined rules of the game data are ensured through the validation capabilities of the schema. Constraints and validations, such as data types, allowed values, and dependencies, can be defined, preventing errors and inconsistencies in the game data. 23 | 24 | Data Consistency 25 | ^^^^^^^^^^^^^^^^ 26 | 27 | Consistency across the game data is achieved through the standardized structure and rules provided by the schema. It enforces a consistent naming convention, attribute definitions, and relationships between entities, thereby enhancing coherence and simplifying collaboration. 28 | 29 | Data Interoperability 30 | ^^^^^^^^^^^^^^^^^^^^^ 31 | 32 | Interoperability and integration with external systems or tools are facilitated by a well-defined schema. By establishing a common language and structure, the schema enables seamless data exchange and collaboration with localization tools, analytics platforms, and asset pipelines. 33 | 34 | Analyzing Game Requirements 35 | --------------------------- 36 | 37 | .. figure:: ./general_design.png 38 | 39 | This step involves analyzing the game requirements to understand the design and functionality of the game. It includes studying the game design document and identifying key features, gameplay mechanics, and data elements that need to be captured and represented in the game. 40 | 41 | Identifying Schemas and Relationships 42 | -------------------------------------- 43 | 44 | .. figure:: ./design_entities.png 45 | In this step, schemas and their relationships within the game are identified. Schemas can be objects, characters, locations, items, quests, or any other significant element in the game. Relationships define how these entities are connected or interact with each other. 46 | 47 | Defining Schemas and Properties 48 | ------------------------------- 49 | 50 | .. figure:: define_schema_property.png 51 | This step involves defining schemas to represent the structure and properties of the game data. A schema serves as a blueprint or template for a specific type of data entity, specifying its properties, attributes, and relationships. Properties describe the characteristics and attributes of an entity, such as its name, description, stats, or any other relevant information. 52 | 53 | .. toctree:: 54 | :caption: Data Types 55 | :titlesonly: 56 | :glob: 57 | 58 | datatypes/* 59 | schemas/* 60 | properties/* 61 | 62 | See also 63 | -------- 64 | 65 | - :doc:`Schema ` 66 | - :doc:`Property ` 67 | - :doc:`Implementing Inheritance ` 68 | - :doc:`Filling Documents ` 69 | - :doc:`Publishing Game Data ` 70 | - :doc:`Generating Source Code ` -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/date.rst: -------------------------------------------------------------------------------- 1 | Date 2 | ==== 3 | 4 | The ``Date`` data type is used to store dates in `ISO 8601 `_ format, which includes the year, month, day, and time with `UTC `_ time zone. This data type is particularly useful for storing information about events that occur on specific dates or for tracking the age of entities. Since dates are stored with `UTC `_ time zone, the data can be consistently interpreted across different time zones. 5 | 6 | 7 | Source Code Type 8 | +-------------------------------------------------------+-----------------------------------------------------------------+ 9 | | Language | Type | 10 | +-------------------------------------------------------+-----------------------------------------------------------------+ 11 | | C# | System.DateTime | 12 | +-------------------------------------------------------+-----------------------------------------------------------------+ 13 | | TypeScript | Date | 14 | +-------------------------------------------------------+-----------------------------------------------------------------+ 15 | | C++ (Unreal Engine) | FDateTime | 16 | +-------------------------------------------------------+-----------------------------------------------------------------+ 17 | | Haxe | Date | 18 | +-------------------------------------------------------+-----------------------------------------------------------------+ 19 | Uniqueness 20 | Date cannot be marked as unique. 21 | Format 22 | ``yyyy-MM-ddTHH:mm:ss.fffZ`` 23 | 24 | Example 25 | ------- 26 | .. code-block:: js 27 | 28 | "2017-12-27T00:00:00.000Z" 29 | 30 | // it is better not to store dates before this mark for compatibility reasons 31 | "1970-01-01T00:00:00.000Z" 32 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/document.rst: -------------------------------------------------------------------------------- 1 | Document 2 | ======== 3 | 4 | The ``Document`` data type in game data schema is used to represent complex structures. A document can contain multiple properties of different data types, including other documents or document collections, allowing for hierarchical data modeling. 5 | It is important to note that the lifetime of sub-documents is tied to the lifetime of the parent document, meaning that any changes (e.g. deletion) to the parent document will affect all of its sub-documents. 6 | 7 | Source Code Type 8 | +-------------------------------------------------------+-----------------------------------------------------------------+ 9 | | Language | Type | 10 | +-------------------------------------------------------+-----------------------------------------------------------------+ 11 | | C# | ``class`` | 12 | +-------------------------------------------------------+-----------------------------------------------------------------+ 13 | | TypeScript | ``class`` | 14 | +-------------------------------------------------------+-----------------------------------------------------------------+ 15 | | C++ (Unreal Engine) | ``UCLASS`` | 16 | +-------------------------------------------------------+-----------------------------------------------------------------+ 17 | | Haxe | ``class`` | 18 | +-------------------------------------------------------+-----------------------------------------------------------------+ 19 | Uniqueness 20 | Document Text cannot be marked as unique. 21 | 22 | Example 23 | ------- 24 | 25 | For example, in a **Dialog**, each node can be a ``Document`` with dialog :doc:`text `, response options, and :doc:`actions ` that occur after a response is chosen. Each response option can be a sub-document that is another **Dialog** node. 26 | 27 | .. code-block:: js 28 | 29 | { 30 | "Text": "Welcome to the game. What's your name?", 31 | "Options": [ 32 | { 33 | "Text": "My name is John.", 34 | "Options": [ 35 | { 36 | "Text": "Hello John! What brings you here?", 37 | "Options": [ 38 | { 39 | "Text": "I'm looking for adventure.", 40 | "Action": "dialog.GiveQuestAndEnd()" 41 | }, 42 | { 43 | "Text": "I'm on a mission.", 44 | "Options": [/* ... */] 45 | } 46 | ] 47 | } 48 | ] 49 | }, 50 | { 51 | "Text": "I prefer not to say.", 52 | "Action": "dialog.End()" 53 | } 54 | ] 55 | } 56 | 57 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/document_collection.rst: -------------------------------------------------------------------------------- 1 | Document Collection 2 | =================== 3 | 4 | The DocumentCollection data type is used to store an array of sub-documents, which are used to represent complex structures. 5 | It is important to note that the lifetime of sub-documents is tied to the lifetime of the parent document, meaning that any changes (e.g. deletion) to the parent document will affect all of its sub-documents. 6 | 7 | Source Code Type 8 | +-------------------------------------------------------+-----------------------------------------------------------------+ 9 | | Language | Type | 10 | +-------------------------------------------------------+-----------------------------------------------------------------+ 11 | | C# | ReadOnlyCollection{T} | 12 | +-------------------------------------------------------+-----------------------------------------------------------------+ 13 | | TypeScript | ReadOnlyArray{T} | 14 | +-------------------------------------------------------+-----------------------------------------------------------------+ 15 | | C++ (Unreal Engine) | TArray{T} | 16 | +-------------------------------------------------------+-----------------------------------------------------------------+ 17 | | Haxe | ReadOnlyArray{T} | 18 | +-------------------------------------------------------+-----------------------------------------------------------------+ 19 | Uniqueness 20 | Document Collection Text cannot be marked as unique. 21 | Size 22 | May be limited in number of items. 0 - no limit. 23 | 24 | Example 25 | ------- 26 | 27 | One example use case for ``DocumentCollection`` is storing a list of items in a game, such as a chest and its contents. Each item in the chest could be represented by a sub-document containing information such as :doc:`reference ` to an item and its :doc:`quantity `. 28 | 29 | .. code-block:: js 30 | 31 | { 32 | "Name": "Silver Chest", 33 | "Loot": [ 34 | { 35 | "Item": { "Id": "Sword" }, 36 | "Quantity": 1 37 | }, 38 | { 39 | "Item": { "Id": "Silver" }, 40 | "Quantity": 100 41 | } 42 | ] 43 | } 44 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/formula.rst: -------------------------------------------------------------------------------- 1 | Formula 2 | ======= 3 | 4 | The **Formula** data type allows storing and evaluating C# expressions within game data. It enables developers to define logic that performs calculations based on dynamic inputs and parameters not known until runtime. A formula can be any valid C# expression that returns a value of a supported data type. 5 | 6 | Formulas are especially useful in scenarios involving complex calculations, such as determining weapon damage based on factors like target resistance and attack type. By encapsulating such logic in formulas, developers can fine-tune gameplay mechanics without modifying or recompiling the source code. 7 | 8 | At runtime, formulas are evaluated using arguments passed to them. These arguments can reference other data properties or objects, providing a high level of flexibility in defining game rules and balancing. 9 | 10 | For example, a damage formula might look like this: 11 | 12 | .. code-block:: js 13 | 14 | (weaponPower * (1.0 - targetResistance)) * attackMultiplier 15 | 16 | This expression multiplies weapon power by a factor based on the target’s resistance and then scales the result by an attack multiplier. The final result is the computed damage. 17 | 18 | 19 | Source Code Type 20 | +-------------------------------------------------------+-----------------------------------------------------------------+ 21 | | Language | Type | 22 | +-------------------------------------------------------+-----------------------------------------------------------------+ 23 | | C# | ``class`` | 24 | +-------------------------------------------------------+-----------------------------------------------------------------+ 25 | | TypeScript | ``class`` | 26 | +-------------------------------------------------------+-----------------------------------------------------------------+ 27 | | C++ (Unreal Engine) | ``UCLASS`` | 28 | +-------------------------------------------------------+-----------------------------------------------------------------+ 29 | | Haxe | ``class`` | 30 | +-------------------------------------------------------+-----------------------------------------------------------------+ 31 | Uniqueness 32 | Formulas cannot be marked as unique. 33 | Specification 34 | Formulas support the following specification parameters: 35 | - ``param.`` — Defines a formula parameter and its type. 36 | 37 | Example: ``param.id=System.Int32`` 38 | - ``resultType`` — Specifies the return type of the formula. 39 | 40 | Example: ``resultType=System.String`` 41 | - ``knownType`` — Declares types known to the formula. Only static members of known types can be accessed. 42 | 43 | Example: ``knownType=System.FMath`` 44 | - ``typeName`` — Custom type name for the generated class. If omitted, a name is derived from the containing schema and property. 45 | 46 | Example: ``typeName=MyDamageCalculatingFormula`` 47 | 48 | Example 49 | ------- 50 | 51 | .. code-block:: js 52 | 53 | "target.HP < 100" 54 | "x != 0" 55 | "target.DoDamage(100)" 56 | "(weapon.Damage / target.DamageResistance) / 2" -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/integer.rst: -------------------------------------------------------------------------------- 1 | Integer 2 | ======= 3 | 4 | The ``Integer`` data type is a whole number data type that is limited to 64 bits. It is used to represent integers without a fractional component. It can be used in cases where you need to store a large range of positive or negative whole numbers, such as in-game currency or player levels. 5 | 6 | Unlike the :doc:`Number ` data type, integers do not have any precision caveats since they do not store decimal values. Therefore, they are suitable for calculations that require exact values. 7 | 8 | Source Code Type 9 | +-------------------------------------------------------+-----------------------------------------------------------------+ 10 | | Language | Type | 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | C# | System.Int32 or System.Int64 | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | TypeScript | number or bigint | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | C++ (Unreal Engine) | int32 or int64 | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | | Haxe | Int or Int64 | 19 | +-------------------------------------------------------+-----------------------------------------------------------------+ 20 | Uniqueness 21 | Integers can be marked as unique. 22 | Size 23 | 32 or 64bit 24 | 25 | Example 26 | ------- 27 | .. code-block:: js 28 | 29 | 0 30 | -1 31 | 100 -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/localized_text.rst: -------------------------------------------------------------------------------- 1 | Localized Text 2 | ============== 3 | 4 | The ``LocalizedText`` data type is used to store text that needs to be displayed in multiple languages. Unlike the :doc:`Text ` data type, the LocalizedText data type allows the storage of the same text in multiple languages. It supports the whole range of UTF symbols, just like the :doc:`Text ` data type. The ``LocalizedText`` data type is essential for games that require localization support, and it makes it easy for game developers to manage text that needs to be displayed in multiple languages. 5 | 6 | Source Code Type 7 | +-------------------------------------------------------+-----------------------------------------------------------------+ 8 | | Language | Type | 9 | +-------------------------------------------------------+-----------------------------------------------------------------+ 10 | | C# | LocalizedText or System.String | 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | TypeScript | LocalizedText or string | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | C++ (Unreal Engine) | FLocalizedText or FText | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | Haxe | LocalizedText or String | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | Uniqueness 19 | Localized Text cannot be marked as unique. 20 | Size 21 | May be limited in number of characters. 0 - no limit. 22 | 23 | Example 24 | ------- 25 | 26 | .. code-block:: js 27 | 28 | {"en-US": "Hello", "fr-FR": "Bonjour"} 29 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/logical.rst: -------------------------------------------------------------------------------- 1 | 2 | Logical 3 | ======= 4 | 5 | The ``Logical`` data type is used to represent boolean values — values that can be either ``true`` or ``false``. It is suitable for modeling simple binary states, conditions, or flags commonly used throughout game data. 6 | 7 | Use Cases 8 | --------- 9 | 10 | The ``Logical`` type is ideal for: 11 | 12 | - Representing **simple state**: 13 | Examples include `IsActive`, `IsPublished`, `IsLatest`, `IsReligious`, or `IsOptional`. 14 | 15 | - Indicating **ownership or structural conditions**: 16 | Examples include `HasPartner`, `HasSecondPhase`. 17 | 18 | - Controlling **behavioral expectations**: 19 | Examples include `ShouldFinishTutorial`, `ShouldGoFirst`. 20 | 21 | - Defining **capabilities or permissions**: 22 | Examples include `CanBlock`, `CanRun`, `CanBeSold`. 23 | 24 | This makes the ``Logical`` type a versatile and lightweight choice for many decision-driven properties in schema design. 25 | 26 | Comparison with MultiPickList 27 | ----------------------------- 28 | 29 | While the :doc:`MultiPickList ` data type can represent combinations of multiple states, the ``Logical`` type is recommended when the property has exactly two possible values. 30 | Using ``Logical`` ensures simplicity, clarity, and optimal editor behavior for binary flags. 31 | 32 | Source Code Type 33 | +-------------------------------------------------------+-----------------------------------------------------------------+ 34 | | Language | Type | 35 | +-------------------------------------------------------+-----------------------------------------------------------------+ 36 | | C# | System.Boolean | 37 | +-------------------------------------------------------+-----------------------------------------------------------------+ 38 | | TypeScript | boolean | 39 | +-------------------------------------------------------+-----------------------------------------------------------------+ 40 | | C++ (Unreal Engine) | bool | 41 | +-------------------------------------------------------+-----------------------------------------------------------------+ 42 | | Haxe | Bool | 43 | +-------------------------------------------------------+-----------------------------------------------------------------+ 44 | Uniqueness 45 | Logical can be marked as unique. 46 | 47 | Example 48 | ------- 49 | .. code-block:: js 50 | 51 | true 52 | false 53 | True 54 | False 55 | 1 56 | 0 57 | "Yes" 58 | "No" 59 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/multi_pick_list.rst: -------------------------------------------------------------------------------- 1 | Multi-Pick List 2 | =============== 3 | 4 | The ``MultiPickList`` data type is used when you want to allow the selection of multiple values from a predefined list of options. It is similar to the :doc:`PickList ` data type, but it allows for multiple selections. 5 | 6 | ``MultiPickList`` is particularly useful when you want to replace several :doc:`Logical ` properties that have a related meaning with a single property. For example, instead of having three separate properties to indicate if a item can be broken, disassembled, or sold, you can use a MultiPickList with the options "CanBeBreaken," "CanBeDisassembled," and "CanBeSold." 7 | 8 | Source Code Type 9 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 10 | | Language | Type | 11 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 12 | | C# | ``[Flags] enum`` | 13 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 14 | | TypeScript | ``enum`` | 15 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 16 | | C++ (Unreal Engine) | ``UENUM(meta = (Bitflags, UseEnumValuesAsMaskValuesInEditor = "true"))`` | 17 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 18 | | Haxe | ``abstract`` | 19 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 20 | Uniqueness 21 | Multi-Pick Lists can be marked as unique. 22 | Size 23 | 32 or 64bit 24 | Specification 25 | Multi-Pick Lists support the following specification parameters: 26 | 27 | - ``typeName`` — Custom type name for the generated class. If omitted, a name is derived from the containing schema and property. 28 | 29 | Example: ``typeName=MyEnum`` 30 | 31 | Example 32 | ------- 33 | .. code-block:: js 34 | 35 | 1 // internaly stored as integers 36 | "Apple" // string values also valid -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/number.rst: -------------------------------------------------------------------------------- 1 | Number 2 | ====== 3 | 4 | The ``Number`` data type is used to represent decimal numbers. It conforms to the `IEEE 754 `_ floating-point standard and can represent both positive and negative numbers, as well as zero. However, due to the limitations of the floating-point representation, precision may be lost when performing certain arithmetic operations. Therefore, it is recommended to use the :doc:`Integer ` data type for financial calculations and other scenarios that require high precision. 5 | 6 | Some use cases for the ``Number`` data type include representing quantities, such as the count of an items or the amount of gold reward in the chest, or representing percentages, such as the chance of an event occurring. It can also be used to represent measurements, such as the height of a character or the length of a weapon. 7 | 8 | When working with ``Numbers`` in game data, it is important to ensure that the precision is appropriate for the use case. Additionally, it may be necessary to round numbers to a certain number of decimal places to avoid displaying unnecessarily precise values to players. 9 | 10 | Source Code Type 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | Language | Type | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | C# | System.Single or System.Double | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | TypeScript | number | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | | C++ (Unreal Engine) | float or double | 19 | +-------------------------------------------------------+-----------------------------------------------------------------+ 20 | | Haxe | Float | 21 | +-------------------------------------------------------+-----------------------------------------------------------------+ 22 | Uniqueness 23 | Numbers can be marked as unique. 24 | Size 25 | 32 or 64bit 26 | Specification 27 | Numbers support the following specification parameters: 28 | 29 | - ``precision`` — Specify decimal precision of stored number. 30 | 31 | Example: ``precision=2`` 32 | - ``displayPrecision`` — Specify decimal precision of displayed in UI number. 33 | 34 | Example: ``displayPrecision=2`` 35 | 36 | Example 37 | ------- 38 | .. code-block:: js 39 | 40 | 3.14 41 | 0.21 42 | -3.14 43 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/pick_list.rst: -------------------------------------------------------------------------------- 1 | Pick List 2 | ========= 3 | 4 | ``PickList`` is a data type used to define a list of pre-defined options for a property. It allows the user to select only one option from the given list. The options can be defined as a string, and the list can contain any number of options. 5 | 6 | ``PickList`` data type is commonly used to define properties such as gender, language, or country, where there are a limited number of options to choose from. It provides a convenient way to standardize the data, and also helps to prevent errors or inconsistencies in the data. 7 | 8 | For example, in a game where the player can choose a character class, the ``PickList`` data type can be used to define the available options, such as "Warrior," "Mage," or "Rogue." This ensures that the player can only choose from the available options and helps to prevent invalid inputs. 9 | 10 | Source Code Type 11 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 12 | | Language | Type | 13 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 14 | | C# | ``enum`` | 15 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 16 | | TypeScript | ``enum`` | 17 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 18 | | C++ (Unreal Engine) | ``UENUM`` | 19 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 20 | | Haxe | ``abstract`` | 21 | +-------------------------------------------------------+--------------------------------------------------------------------------+ 22 | Uniqueness 23 | Pick Lists can be marked as unique. 24 | Size 25 | 32 or 64bit 26 | Specification 27 | Pick Lists support the following specification parameters: 28 | 29 | - ``typeName`` — Custom type name for the generated class. If omitted, a name is derived from the containing schema and property. 30 | 31 | Example: ``typeName=MyEnum`` 32 | 33 | Example 34 | ------- 35 | .. code-block:: js 36 | 37 | 1 // internaly stored as integers 38 | "Apple" // string values also valid -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/reference.rst: -------------------------------------------------------------------------------- 1 | Reference 2 | ========= 3 | 4 | The ``Reference`` data type enables the creation of non-embedded relationships between documents. A reference acts as a pointer to another document by using that document's ``Id`` as a key. This approach facilitates linking between related documents without the need to duplicate or embed data. 5 | 6 | When using a ``Reference``, the target documents are not stored within the parent document but are instead referenced externally. This is particularly beneficial when working with large or complex data sets, where referencing is more efficient and maintains separation of concerns. It also promotes data integrity by ensuring that only valid document references are maintained. 7 | 8 | For example, in a game scenario, a **Chest** with a loot table might hold a reference to an **Item** document, rather than embedding the entire **Item** directly within the **Chest**. This separation allows independent management of the loot logic and item definitions while preserving their relationships. 9 | 10 | Source Code Type 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | Language | Type | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | C# | DocumentReference{T} or T | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | TypeScript | DocumentReference{T} or T | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | | C++ (Unreal Engine) | FGameDataDocumentReference | 19 | +-------------------------------------------------------+-----------------------------------------------------------------+ 20 | | Haxe | DocumentReference{T} or T | 21 | +-------------------------------------------------------+-----------------------------------------------------------------+ 22 | Uniqueness 23 | Reference cannot be marked as unique. 24 | Specification 25 | References support the following specification parameter: 26 | 27 | - ``displayTextTemplate`` — Defines a template string for how the referenced value is displayed in the UI. 28 | 29 | Example: 30 | ``displayTextTemplate=Item%3A+%7BName%7D%2C+Count%3A+%7BCount%7D`` 31 | (renders as: `Item: {Name}, Count: {Count}`) 32 | 33 | Example 34 | ------- 35 | 36 | .. code-block:: js 37 | 38 | { "Id": "Sword" } 39 | "Sword" // just raw Id is also accepted 40 | 41 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/reference_collection.rst: -------------------------------------------------------------------------------- 1 | Reference Collection 2 | ==================== 3 | 4 | The ``ReferenceCollection`` data type is used to create non-embedded, one-to-many relationships between documents. It allows a document to reference multiple documents of the same type without embedding them directly. 5 | 6 | When using a ``ReferenceCollection``, the referenced documents are stored as references to their original locations, rather than being embedded in the parent document. This approach is particularly useful when dealing with large or complex datasets where referencing is more efficient and scalable than embedding. It also helps maintain data integrity by ensuring that all references point to valid documents. 7 | 8 | For example, in a game, each **Quest** may reference a collection of **Objectives**. These objectives can be defined separately for reuse across multiple quests. The ``ReferenceCollection`` data type enables the quest document to maintain a list of references to objective documents. 9 | 10 | Source Code Type 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | Language | Type | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | C# | ReadOnlyCollection{T} | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | TypeScript | ReadOnlyArray{T} | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | | C++ (Unreal Engine) | TArray{T} | 19 | +-------------------------------------------------------+-----------------------------------------------------------------+ 20 | | Haxe | ReadOnlyArray{T} | 21 | +-------------------------------------------------------+-----------------------------------------------------------------+ 22 | Uniqueness 23 | Reference Collection cannot be marked as unique. 24 | Size 25 | May be limited in number of items. 0 - no limit. 26 | Specification 27 | References support the following specification parameter: 28 | 29 | - ``displayTextTemplate`` — Defines a template string for how the referenced value is displayed in the UI. 30 | 31 | Example: 32 | ``displayTextTemplate=Item%3A+%7BName%7D%2C+Count%3A+%7BCount%7D`` 33 | (renders as: `Item: {Name}, Count: {Count}`) 34 | 35 | Example 36 | ------- 37 | 38 | .. code-block:: js 39 | 40 | [{ "Id": "Sword" }, { "Id": "Gold" }] 41 | ["Sword", "Gold"] // just raw Ids are also accepted 42 | 43 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/text.rst: -------------------------------------------------------------------------------- 1 | Text 2 | ==== 3 | 4 | The ``Text`` data type is used to store simple text values in game data. Unlike the :doc:`LocalizedText ` data type, ``Text`` does not have support for multiple translations of the same text. Instead, it allows for the storage of any UTF symbol in a single language. This data type is useful for fields that do not require localization, such as character names, item descriptions, or game lore. 5 | 6 | Source Code Type 7 | +-------------------------------------------------------+-----------------------------------------------------------------+ 8 | | Language | Type | 9 | +-------------------------------------------------------+-----------------------------------------------------------------+ 10 | | C# | System.String | 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | TypeScript | string | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | C++ (Unreal Engine) | FString | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | Haxe | String | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | Uniqueness 19 | Text can be marked as unique (case sensitive for uniqueness purposes). 20 | Size 21 | May be limited in number of characters. 0 - no limit. 22 | 23 | Example 24 | ------- 25 | 26 | .. code-block:: js 27 | 28 | "Hello world!" 29 | 30 | Sub-Types 31 | --------- 32 | - :doc:`Asset Path <../sub/asset>` 33 | - :doc:`Asset Path Collection <../sub/asset_collection>` 34 | - :doc:`Vector 2/3/4 <../sub/vector>` 35 | - :doc:`Integer Vector 2/3/4<../sub/vector_int>` 36 | - :doc:`Rectangle<../sub/rectangle>` 37 | - :doc:`Integer Rectangle<../sub/rectangle_int>` 38 | - :doc:`Tags<../sub/tags>` -------------------------------------------------------------------------------- /docs/gamedata/datatypes/all/time.rst: -------------------------------------------------------------------------------- 1 | Time 2 | ==== 3 | 4 | The ``Time`` data type in game data is equivalent to the ``TimeSpan`` data type in C#. It is used to store a duration or a time interval, such as the time it takes to complete a task or the length of a cutscene in a game. The ``Time`` data type is represented as a string in the format ``HH:mm:ss``, where HH is the number of hours, mm is the number of minutes, and ss is the number of seconds. 5 | 6 | For example, if a task takes 2 hours and 30 minutes to complete, the ``Time`` data type value would be ``02:30:00``. 7 | 8 | Source Code Type 9 | +-------------------------------------------------------+-----------------------------------------------------------------+ 10 | | Language | Type | 11 | +-------------------------------------------------------+-----------------------------------------------------------------+ 12 | | C# | System.TimeSpan | 13 | +-------------------------------------------------------+-----------------------------------------------------------------+ 14 | | TypeScript | TimeSpan (Bundled) | 15 | +-------------------------------------------------------+-----------------------------------------------------------------+ 16 | | C++ (Unreal Engine) | FTimespan | 17 | +-------------------------------------------------------+-----------------------------------------------------------------+ 18 | | Haxe | TimeSpan (Bundled) | 19 | +-------------------------------------------------------+-----------------------------------------------------------------+ 20 | Uniqueness 21 | Time cannot be marked as unique. 22 | Format 23 | ``[DD.]HH:mm:ss`` or ```` 24 | 25 | Example 26 | ------- 27 | .. code-block:: js 28 | 29 | "02:30:00" // 2 hours and 30 minutes 30 | "1.00:00:00" // 1 day 31 | 60 // 60 seconds 32 | 120 // two minutes 33 | 34 | "-00:30:00" // could be negative 35 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/asset.rst: -------------------------------------------------------------------------------- 1 | Asset Path 2 | ========== 3 | 4 | The ``Asset Path`` is a sub-type of the :doc:`Text <../all/text>` data type and is used to store a path to a game asset within game data. 5 | 6 | The ``Asset Path Collection`` is a collection variant of this type and it is used to store multiple paths. Each path is separated by the ``|`` (pipe) character. 7 | 8 | Paths are typically relative to the project root and can be used to load assets directly at runtime. 9 | 10 | Specification 11 | ------------- 12 | 13 | Asset Path Collection supports the following specification parameters: 14 | 15 | - ``assetType`` — Filters the types of assets to select. 16 | For Unity and Unreal Engine, this refers to class names. 17 | For standalone builds, it refers to file extensions. 18 | Example: ``assetType=Texture`` or ``assetType=Texture2D`` 19 | 20 | UI Behavior 21 | ----------- 22 | 23 | This field is represented in the editor by a multi-select searchable input. 24 | Users can type to search for assets and add multiple items to the collection using auto-complete. 25 | 26 | The search input supports the ``t:`` filter pattern to limit search results by asset type. 27 | 28 | Examples: 29 | 30 | - Unity: ``swing t:AudioClip`` 31 | - Unreal Engine: ``swing t:SoundWave`` 32 | - Standalone: ``swing t:wav`` 33 | 34 | Validation Behavior 35 | ------------------- 36 | 37 | The Charon editor does not validate asset paths during game data loading (i.e., at runtime). 38 | You are responsible for ensuring the existence of assets at the provided paths. 39 | To improve reliability, consider writing a custom editor extension that validates all asset references before packaging the game. 40 | 41 | Asset Localization 42 | ------------------ 43 | 44 | Localizable asset paths are not currently supported. 45 | If this is a required feature, you are encouraged to suggest it in Charon’s `Discord `_ channel. 46 | 47 | Path Origin 48 | ----------- 49 | 50 | The meaning of "relative path" for asset references depends on how the game data editor is launched: 51 | 52 | - **Unity Editor**: 53 | Paths are relative to the Unity project root directory, typically the directory containing the ``Assets`` folder. 54 | Asset paths will usually start with ``Assets/``. 55 | Example: ``Assets/Textures/MyTexture.png`` 56 | 57 | - **Unreal Engine Editor**: 58 | Paths are relative to the Unreal project root directory, usually containing the ``Content`` folder. 59 | Asset paths often start with ``/Game/`` because it is Unreal Engine package path, not physical path. 60 | Example: ``/Game/Textures/MyTexture`` 61 | 62 | - **Standalone Execution** (via CLI): 63 | Paths are relative to the game data file path by default. 64 | This behavior can be customized using either: 65 | 66 | - The ``--gameAssetsPath`` CLI argument: 67 | ``dotnet tool charon ./gamedata.gdjs --gameAssetsPath "C:/Projects/MyGame/"`` 68 | 69 | - The ``STANDALONE__GAMEASSETSPATH`` environment variable. 70 | 71 | Example 72 | ------- 73 | 74 | .. code-block:: js 75 | 76 | "Assets/Textures/MyTexture.png" // Unity 77 | "/Game/Textures/MyTexture" // Unreal Engine 78 | "Textures/MyTexture.png" // Standalone 79 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/rectangle.rst: -------------------------------------------------------------------------------- 1 | Rectangle 2 | ========= 3 | 4 | The ``Rectangle`` is a sub-type of the :doc:`Text <../all/text>` data type used to store four decimal values representing a rectangle. The components represent ``X``, ``Y``, ``Width``, and ``Height``, in that order. Values are separated by spaces and must be parsed from the string before use at runtime. 5 | 6 | UI Behavior 7 | ----------- 8 | 9 | This field is represented in the editor as a group of input fields labeled ``X``, ``Y``, ``Width``, and ``Height``. Each component accepts decimal numbers. 10 | 11 | Validation Behavior 12 | ------------------- 13 | 14 | The editor ensures that a valid rectangle value is entered and only stores properly formatted values. However, there is no runtime validation or built-in parsing logic, so values must be parsed manually in game code. 15 | 16 | Example 17 | ------- 18 | 19 | .. code-block:: js 20 | 21 | "50.0 100.0 200.5 25.0" 22 | 23 | Parsing 24 | ------- 25 | 26 | **Unity (C#) example:** 27 | 28 | .. code-block:: cs 29 | 30 | var uiElement = gameData.AllUIElements.Get("HealthBar"); // -> UIElement 31 | var boundsString = uiElement.Bounds; // -> "50.0 100.0 200.5 25.0" 32 | var components = boundsString.Split(' '); 33 | var bounds = new Rect( 34 | float.Parse(components[0]), // X 35 | float.Parse(components[1]), // Y 36 | float.Parse(components[2]), // Width 37 | float.Parse(components[3]) // Height 38 | ); 39 | 40 | **Unreal Engine (C++) example:** 41 | 42 | .. code-block:: cpp 43 | 44 | auto UIElement = GameData->AllUIElements->Find(TEXT("HealthBar")); // -> UUIElement* 45 | FString BoundsString = UIElement->Bounds; // -> "50.0 100.0 200.5 25.0" 46 | TArray Components; 47 | BoundsString.ParseIntoArray(Components, TEXT(" ")); 48 | FSlateRect Bounds( 49 | FCString::Atof(*Components[0]), // X 50 | FCString::Atof(*Components[1]), // Y 51 | FCString::Atof(*Components[2]), // Width 52 | FCString::Atof(*Components[3]) // Height 53 | ); 54 | 55 | **TypeScript example:** 56 | 57 | .. code-block:: ts 58 | 59 | let uiElement = gameData.uiElementsAll.find("HealthBar"); // -> UIElement 60 | let boundsString = uiElement.Bounds; // -> "50.0 100.0 200.5 25.0" 61 | let parts = boundsString.split(" ").map(x => parseFloat(x)); 62 | let bounds = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] }; 63 | 64 | **Haxe example:** 65 | 66 | .. code-block:: haxe 67 | 68 | var uiElement = gameData.uiElementsAll.get("HealthBar"); // -> UIElement 69 | var boundsString = uiElement.Bounds; // -> "50.0 100.0 200.5 25.0" 70 | var parts = boundsString.split(" ").map(Std.parseFloat); 71 | var bounds = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] }; 72 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/rectangle_int.rst: -------------------------------------------------------------------------------- 1 | Integer Rectangle 2 | ================= 3 | 4 | The ``Integer Rectangle`` (``RectangleInt``) is a sub-type of the :doc:`Text <../all/text>` data type used to store four integer values representing a rectangle. The components represent ``X``, ``Y``, ``Width``, and ``Height``, in that order. Values are separated by spaces and must be parsed from the string before use at runtime. 5 | 6 | UI Behavior 7 | ----------- 8 | 9 | This field is represented in the editor as a group of input fields labeled ``X``, ``Y``, ``Width``, and ``Height``. Each component accepts only whole numbers (integers). 10 | 11 | Validation Behavior 12 | ------------------- 13 | 14 | The editor ensures that a valid integer rectangle is entered and only stores properly formatted values. However, there is no runtime validation or built-in parsing logic, so values must be parsed manually in game code. 15 | 16 | Example 17 | ------- 18 | 19 | .. code-block:: js 20 | 21 | "50 100 200 25" 22 | 23 | Parsing 24 | ------- 25 | 26 | **Unity (C#) example:** 27 | 28 | .. code-block:: cs 29 | 30 | var uiElement = gameData.AllUIElements.Get("HealthBar"); // -> UIElement 31 | var boundsString = uiElement.Bounds; // -> "50 100 200 25" 32 | var components = boundsString.Split(' '); 33 | var bounds = new RectInt( 34 | int.Parse(components[0]), // X 35 | int.Parse(components[1]), // Y 36 | int.Parse(components[2]), // Width 37 | int.Parse(components[3]) // Height 38 | ); 39 | 40 | **Unreal Engine (C++) example:** 41 | 42 | .. code-block:: cpp 43 | 44 | auto UIElement = GameData->AllUIElements->Find(TEXT("HealthBar")); // -> UUIElement* 45 | FString BoundsString = UIElement->Bounds; // -> "50 100 200 25" 46 | TArray Components; 47 | BoundsString.ParseIntoArray(Components, TEXT(" ")); 48 | FIntRect Bounds( 49 | FCString::Atoi(*Components[0]), // X 50 | FCString::Atoi(*Components[1]), // Y 51 | FCString::Atoi(*Components[2]), // Width 52 | FCString::Atoi(*Components[3]) // Height 53 | ); 54 | 55 | **TypeScript example:** 56 | 57 | .. code-block:: ts 58 | 59 | let uiElement = gameData.uiElementsAll.find("HealthBar"); // -> UIElement 60 | let boundsString = uiElement.Bounds; // -> "50 100 200 25" 61 | let parts = boundsString.split(" ").map(x => parseInt(x, 10)); 62 | let bounds = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] }; 63 | 64 | **Haxe example:** 65 | 66 | .. code-block:: haxe 67 | 68 | var uiElement = gameData.uiElementsAll.get("HealthBar"); // -> UIElement 69 | var boundsString = uiElement.Bounds; // -> "50 100 200 25" 70 | var parts = boundsString.split(" ").map(Std.parseInt); 71 | var bounds = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] }; 72 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/tags.rst: -------------------------------------------------------------------------------- 1 | Tags 2 | ==== 3 | 4 | The ``Tag`` data type is a sub-type of the :doc:`Text <../all/text>` data type and is used to store a reusable set of tag values (e.g., "fire", "enemy", "magic") that can be shared across multiple documents. 5 | 6 | The ``Tag Collection`` is a collection variant of this type and it is used to store multiple tags. Each tag is separated by the `` `` (space) character. 7 | 8 | UI Behavior 9 | ----------- 10 | 11 | In the editor, this field is represented as a list of chips/pills/tokens with support for free-form input and autocompletion of existing tags. 12 | Note that autocompletion relies on scanning all documents of the same type to extract available tags, so performance considerations should be made when using this data type at scale. 13 | 14 | Validation Behavior 15 | ------------------- 16 | 17 | The Charon editor does not validate tags during game data loading (i.e., at runtime). Ensure that your game logic handles any missing or unexpected tags appropriately. 18 | 19 | Relation to Multi-Pick List 20 | --------------------------- 21 | 22 | Tags are similar to the :doc:`Multi-Pick List <../all/multi_pick_list>` data type but offer more flexibility by allowing free-form input. 23 | C-style named tags can be easily converted to a Multi-Pick List by changing the property type. 24 | Likewise, Multi-Pick List values can be converted back to Tags if strict value control is no longer needed. 25 | 26 | Example 27 | ------- 28 | 29 | .. code-block:: js 30 | 31 | "fire" 32 | "poison magical non-resistable" -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/vector.rst: -------------------------------------------------------------------------------- 1 | Vector 2/3/4 2 | ============ 3 | 4 | The ``Vector 2/3/4`` is a sub-type of the :doc:`Text <../all/text>` data type used to store a group of 2, 3, or 4 decimal values. These values are space-separated and must be parsed from the string before use at runtime. 5 | 6 | UI Behavior 7 | ----------- 8 | 9 | This field is represented in the editor as a group of input fields, each allowing the user to enter one component of the vector (e.g., X, Y, Z). 10 | 11 | Validation Behavior 12 | ------------------- 13 | 14 | The editor ensures that a valid vector is entered and only stores properly formatted values. However, there is no runtime validation or built-in parsing logic, so the value must be manually parsed in game code. 15 | 16 | Example 17 | ------- 18 | 19 | .. code-block:: js 20 | 21 | "120.1 56.3 30.0" 22 | 23 | Parsing 24 | ------- 25 | 26 | **Unity (C#) example:** 27 | 28 | .. code-block:: cs 29 | 30 | var hero = gameData.AllHeroes.Get("Knight"); // -> Hero 31 | var startingLocationString = hero.StartingLocation; // -> "120.1 56.3 30.0" 32 | var components = startingLocationString.Split(' '); 33 | var startingLocation = new Vector3( 34 | float.Parse(components[0]), 35 | float.Parse(components[1]), 36 | float.Parse(components[2]) 37 | ); 38 | 39 | **Unreal Engine (C++) example:** 40 | 41 | .. code-block:: cpp 42 | 43 | auto Hero = GameData->AllHeroes->Find(TEXT("Knight")); // -> UHero* 44 | FString StartingLocationString = Hero->StartingLocation; // -> "120.1 56.3 30.0" 45 | TArray Components; 46 | StartingLocationString.ParseIntoArray(Components, TEXT(" ")); 47 | FVector StartingLocation = FVector( 48 | FCString::Atof(*Components[0]), 49 | FCString::Atof(*Components[1]), 50 | FCString::Atof(*Components[2]) 51 | ); 52 | 53 | **TypeScript example:** 54 | 55 | .. code-block:: ts 56 | 57 | let hero = gameData.heroesAll.find("Knight"); // -> Hero 58 | let startingLocationString = hero.StartingLocation; // -> "120.1 56.3 30.0" 59 | let parts = startingLocationString.split(" ").map(parseFloat); 60 | let startingLocation: [number, number, number] = [parts[0], parts[1], parts[2]]; 61 | 62 | **Haxe example:** 63 | 64 | .. code-block:: haxe 65 | 66 | var heroById = gameData.heroesAll.get("Knight"); // -> Hero 67 | var startingLocationString = heroById.StartingLocation; // -> "120.1 56.3 30.0" 68 | var parts = startingLocationString.split(" ").map(Std.parseFloat); 69 | var startingLocation = { x: parts[0], y: parts[1], z: parts[2] }; 70 | -------------------------------------------------------------------------------- /docs/gamedata/datatypes/sub/vector_int.rst: -------------------------------------------------------------------------------- 1 | Integer Vector 2/3/4 2 | ==================== 3 | 4 | The ``Integer Vector 2/3/4`` is a sub-type of the :doc:`Text <../all/text>` data type used to store a group of 2, 3, or 4 integer (whole number) values. Values are separated by spaces and must be parsed from the string before use at runtime. 5 | 6 | UI Behavior 7 | ----------- 8 | 9 | This field is represented in the editor as a group of input fields, allowing the user to enter each component of the vector (e.g., X, Y, Z) as whole numbers. 10 | 11 | Validation Behavior 12 | ------------------- 13 | 14 | The editor ensures that a valid integer vector is entered and only stores properly formatted values. However, there is no runtime validation or built-in parsing logic, so the value must be manually parsed in game code. 15 | 16 | Example 17 | ------- 18 | 19 | .. code-block:: js 20 | 21 | "10 20 5" 22 | 23 | Parsing 24 | ------- 25 | 26 | **Unity (C#) example:** 27 | 28 | .. code-block:: cs 29 | 30 | var hero = gameData.AllHeroes.Get("Knight"); // -> Hero 31 | var gridPositionString = hero.StartingLocation; // -> "10 20 5" 32 | var components = gridPositionString.Split(' '); 33 | var startingLocation = new Vector3Int( 34 | int.Parse(components[0]), 35 | int.Parse(components[1]), 36 | int.Parse(components[2]) 37 | ); 38 | 39 | **Unreal Engine (C++) example:** 40 | 41 | .. code-block:: cpp 42 | 43 | auto Hero = GameData->AllHeroes->Find(TEXT("Knight")); // -> UHero* 44 | FString GridPositionString = Hero->StartingLocation; // -> "10 20 5" 45 | TArray Components; 46 | GridPositionString.ParseIntoArray(Components, TEXT(" ")); 47 | FIntVector StartingLocation = FIntVector( 48 | FCString::Atoi(*Components[0]), 49 | FCString::Atoi(*Components[1]), 50 | FCString::Atoi(*Components[2]) 51 | ); 52 | 53 | **TypeScript example:** 54 | 55 | .. code-block:: ts 56 | 57 | let hero = gameData.heroesAll.find("Knight"); // -> Hero 58 | let gridPositionString = hero.StartingLocation; // -> "10 20 5" 59 | let parts = gridPositionString.split(" ").map(x => parseInt(x, 10)); 60 | let startingLocation: [number, number, number] = [parts[0], parts[1], parts[2]]; 61 | 62 | **Haxe example:** 63 | 64 | .. code-block:: haxe 65 | 66 | var heroById = gameData.heroesAll.get("Knight"); // -> Hero 67 | var gridPositionString = heroById.StartingLocation; // -> "10 20 5" 68 | var parts = gridPositionString.split(" ").map(Std.parseInt); 69 | var startingLocation = { x: parts[0], y: parts[1], z: parts[2] }; 70 | -------------------------------------------------------------------------------- /docs/gamedata/define_schema_property.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/define_schema_property.png -------------------------------------------------------------------------------- /docs/gamedata/design_entities.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/design_entities.png -------------------------------------------------------------------------------- /docs/gamedata/enemy_schema_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/enemy_schema_example.png -------------------------------------------------------------------------------- /docs/gamedata/filling_documents.rst: -------------------------------------------------------------------------------- 1 | Filling Documents 2 | ================= 3 | 4 | Once the game data structure has been defined, there are several methods available for creating and populating game entities. One option is to import game data from other sources, such as tables or JSON files. Another option is to generate data using external tools and import it into the editor. Finally, data can be added gradually as development progresses using the game data editor. 5 | 6 | Importing JSON files 7 | -------------------- 8 | JSON files can be imported via the user interface by following these steps: 9 | 10 | 1. Navigate to the document collection page. 11 | 2. Click on ``Actions → Import...``. 12 | 3. Select the JSON file and follow the steps in the import wizard. 13 | 14 | :ref:`See structure requirements. ` 15 | 16 | Exporting to Spreadsheet and Importing Back 17 | ------------------------------------------- 18 | To export game data to a spreadsheet for editing and then import it back, follow these steps: 19 | 20 | 1. Navigate to the document collection page. 21 | 2. Click on ``Actions → Export To → Spreadsheet (.xlsx)`` to export the data to a spreadsheet file. 22 | 3. Open the downloaded file and make the necessary edits. 23 | 4. Import the modified data back into the system: 24 | a. Drag and drop the edited file onto the document collection page. 25 | b. Alternatively, click on ``Actions → Import...`` and follow the steps in the import wizard to select and import the modified file. 26 | 27 | Adding New Document 28 | ------------------- 29 | To create a new document using the user interface, follow these steps: 30 | 31 | 1. Navigate to the document collection page. 32 | 2. Click on the ``Create`` button. 33 | 3. Fill in the required fields in the form provided. 34 | 4. Click ``Save`` to save the new document. 35 | 36 | See also 37 | -------- 38 | 39 | - :doc:`Publishing Game Data ` 40 | - :doc:`Generating Source Code ` -------------------------------------------------------------------------------- /docs/gamedata/general_design.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/general_design.png -------------------------------------------------------------------------------- /docs/gamedata/generating_source_code.rst: -------------------------------------------------------------------------------- 1 | Generating Source Code 2 | =========================== 3 | 4 | The process of generating source code allows game data to be used inside a game. This process involves specifying the language (e.g. C#) and various generation parameters/optimizations. It can be done from both the project's dashboard user interface and the command-line interface (CLI). 5 | 6 | 7 | .. csv-table:: Features 8 | :file: source_code_features.csv 9 | :header-rows: 1 10 | 11 | Using Project's Dashboard UI 12 | ----------------------------- 13 | 14 | To generate source code from the dashboard, follow these steps: 15 | 16 | 1. Go to the dashboard of the project where you want to generate source code. 17 | 2. Click on the *Generate Source Code* button. 18 | 3. Choose the language you want to generate the source code in. 19 | 4. Specify any generation parameters required. 20 | 5. Click on the *Generate* button to initiate the process. 21 | 6. Download archive file with generated source code. 22 | 23 | Using Command-Line Interface (CLI) 24 | ----------------------------------- 25 | 26 | To generate source code from the CLI, follow these steps: 27 | 28 | 1. Open the command-line interface. 29 | 2. Navigate to the game data's directory. 30 | 3. Use the ``GENERATE `` command to generate the source code, specifying the target language and any generation parameters require. 31 | 32 | Example 33 | -------- 34 | 35 | .. code-block:: bash 36 | 37 | dotnet charon GENERATE CSHARPCODE --dataBase "c:\my app\gamedata.json" --namespace "MyGame.Parameters" --outputDirectory "c:\my app\scripts" 38 | 39 | - Use the ``--outputDirectory`` parameter to specify the location where generated files will be saved. 40 | - Use the ``--namespace`` and ``--gameDataClassName`` parameters to adjust the signature of generated classes. 41 | - Use the ``--splitFiles`` parameter to generate multiple files instead of one large one. 42 | - Use the ``--clearOutputDirectory`` parameter to clear the output directory from generated files when re-generating source code. 43 | 44 | Once the process is complete, the generated source code will be available at ``--outputDirectory``. 45 | 46 | See also 47 | -------- 48 | 49 | - :doc:`Publishing Game Data ` 50 | - :doc:`Working with Source Code (C# 4.0) ` 51 | - :doc:`Working with Source Code (C# 7.3) ` 52 | - :doc:`Working with Source Code (TypeScript) ` 53 | - :doc:`Working with Source Code (UE C++) ` 54 | - :doc:`Working with Source Code (Haxe) ` 55 | - :doc:`Command Line Interface (CLI) <../advanced/command_line>` 56 | - :doc:`GENERATE CSHARPCODE Command <../advanced/commands/generate_csharp_code>` 57 | - :doc:`GENERATE TYPESCRIPTCODE Command <../advanced/commands/generate_typescript_code>` 58 | - :doc:`GENERATE UECPP Command <../advanced/commands/generate_uecpp_code>` 59 | - :doc:`GENERATE HAXE Command <../advanced/commands/generate_haxe_code>` 60 | -------------------------------------------------------------------------------- /docs/gamedata/inheritance.rst: -------------------------------------------------------------------------------- 1 | Implementing Inheritance 2 | ======================== 3 | 4 | Inheritance is a familiar tool for programmers when working with shared behavior or data. Unfortunately, it is not natively supported in Charon. However, you can achieve similar functionality using alternative approaches. 5 | 6 | 7 | For example, imagine you have three different document types: ``Armor``, ``Weapon``, and ``Shield``. You want to include all these items in a ``Shop`` list of sellable goods. In traditional inheritance, you could create a base type to unify these documents and refer to it. 8 | 9 | .. figure:: ./inheritance_start.png 10 | 11 | Without inheritance, here are three possible approaches: 12 | 13 | 1. Composition 14 | --------------- 15 | 16 | Extract the shared data from all sellable item types into a separate document type called ``Item``. Each sellable document (e.g., ``Armor``, ``Weapon``, ``Shield``) should include an embedded ``Item`` document containing store-relevant information. In the ``Shop`` list of sellable goods, you can store references to ``Item`` documents. 17 | 18 | .. figure:: ./inheritance_composition.png 19 | 20 | 2. Merging 21 | ---------- 22 | 23 | Alternatively, combine the three document types (``Armor``, ``Weapon``, and ``Shield``) into a single document type called ``Item``. This document will contain fields for all three original types, along with an additional ``Type`` field to specify the item's category. The ``Shop`` list can then store references to these unified ``Item`` documents. 24 | 25 | .. figure:: ./inheritance_merging.png 26 | 27 | 3. Aggregation 28 | -------------- 29 | 30 | As a less elegant alternative, introduce a ``ShopItem`` type with fields referencing all possible document types (``Armor``, ``Weapon``, and ``Shield``). In each ``ShopItem`` document, only one of these fields will be filled, depending on the item's type. The ``Shop`` list can then reference ``ShopItem`` documents. 31 | 32 | .. figure:: ./inheritance_aggregation.png 33 | 34 | Conclusion 35 | ---------- 36 | 37 | Each of these methods has its trade-offs in terms of simplicity, flexibility, and performance. Choosing the right approach depends on your application's requirements and the expected complexity of your data model. 38 | 39 | See also 40 | -------- 41 | 42 | - :doc:`Creating Document Type (Schema) ` 43 | - :doc:`Filling Documents ` 44 | - :doc:`Publishing Game Data ` 45 | - :doc:`Generating Source Code ` -------------------------------------------------------------------------------- /docs/gamedata/inheritance_aggregation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/inheritance_aggregation.png -------------------------------------------------------------------------------- /docs/gamedata/inheritance_composition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/inheritance_composition.png -------------------------------------------------------------------------------- /docs/gamedata/inheritance_merging.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/inheritance_merging.png -------------------------------------------------------------------------------- /docs/gamedata/inheritance_start.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gamedevware/charon/493badfc85a8d957ef072778367cc4c3b6d83af0/docs/gamedata/inheritance_start.png -------------------------------------------------------------------------------- /docs/gamedata/properties/id_property.rst: -------------------------------------------------------------------------------- 1 | Id Property 2 | =========== 3 | 4 | Each schema includes an ``Id`` property that defines the unique identifier for a document. 5 | This property is always named ``Id`` and must satisfy the following constraints: 6 | 7 | - Must be unique. 8 | - Required and must be non-empty (for ``Text`` data type). 9 | - Must use a data type with a stable text representation and comparison support, such as: 10 | 11 | - Time 12 | - Date 13 | - Number 14 | - Integer 15 | - Text 16 | - MultiPickList 17 | - PickList 18 | 19 | Generated Id 20 | ------------- 21 | 22 | Schemas can specify that the ``Id`` property should be automatically generated. 23 | Based on the selected ``Id Generator`` type, an appropriate ``Id`` property will be added to the schema. 24 | 25 | Supported Id Generators: 26 | 27 | - ObjectId 28 | - Guid 29 | - Sequence 30 | - GlobalSequence 31 | 32 | Generated ObjectId 33 | ^^^^^^^^^^^^^^^^^^ 34 | 35 | A BSON ObjectId is a 96-bit unique identifier derived from the machine name, process ID, and timestamp. 36 | It is always increasing and well-suited for sorting documents by creation time. 37 | 38 | Id property details: 39 | 40 | - **Data Type:** Text 41 | - **Size:** 24 characters 42 | - **Requirement:** Not Empty 43 | - **Example:** "049bc0604c363a980b000088" 44 | 45 | Generated Guid 46 | ^^^^^^^^^^^^^^ 47 | 48 | A GUID (Globally Unique Identifier) is a 128-bit identifier typically represented as a 32-character hexadecimal string. 49 | It ensures global uniqueness across systems. 50 | 51 | Id property details: 52 | 53 | - **Data Type:** Text 54 | - **Size:** 32 characters 55 | - **Requirement:** Not Empty 56 | - **Example:** "6fe4202b1b9c4565b439980138524112" 57 | 58 | Generated Sequence 59 | ^^^^^^^^^^^^^^^^^^ 60 | 61 | A sequential numeric identifier unique to each document within a specific schema. 62 | Documents from different schemas may share the same numeric ``Id``. 63 | For globally unique numeric IDs, use ``GlobalSequence``. 64 | 65 | Id property details: 66 | 67 | - **Data Type:** Integer 68 | - **Size:** 32-bit 69 | - **Requirement:** Not Null 70 | - **Example:** 1 71 | 72 | Generated Global Sequence 73 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 74 | 75 | A globally unique numeric identifier across all schemas and documents in the project. 76 | 77 | Id property details: 78 | 79 | - **Data Type:** Integer 80 | - **Size:** 32-bit 81 | - **Requirement:** Not Null 82 | - **Example:** 69 83 | 84 | Non-Generated Id 85 | ---------------- 86 | 87 | Schemas may also use a manually defined ``Id`` property by selecting the ``None`` option for the ``Id Generator``. 88 | You can define the ``Id`` property using any supported data type listed above. 89 | 90 | All Id constraints will be automatically validated when saving the schema. 91 | You can change a schema's ``Id Generator`` to ``None`` at any time, but you cannot switch back to a generator once this change is made. 92 | 93 | Id Placeholder 94 | -------------- 95 | 96 | If you want to assign a temporary value to the ID of a document being created—for example, for internal reference—you can use a placeholder string such as ``_ID_XXX_ANY_UNIQUE_TEXT_HERE_XXX``. 97 | This placeholder will be automatically replaced with the actual generated ID during saving or importing. 98 | 99 | Before save: 100 | 101 | .. code-block:: json 102 | 103 | { 104 | "Id": "_ID_ITEM_123", 105 | "Name": "My New Item", 106 | "ItemReference": { 107 | "Id": "_ID_ITEM_123", // self-reference 108 | "DisplayName": "My New Item" 109 | } 110 | } 111 | 112 | After save: 113 | 114 | .. code-block:: json 115 | 116 | { 117 | "Id": 42, 118 | "Name": "My New Item", 119 | "ItemReference": { 120 | "Id": 42, 121 | "DisplayName": "My New Item" 122 | } 123 | } 124 | 125 | 126 | See also 127 | -------- 128 | 129 | - :doc:`Schema <../schemas/schema>` 130 | - :doc:`Property ` 131 | - :doc:`Shared Property ` 132 | - :doc:`All Data Types <../datatypes/list>` 133 | - :doc:`Creating Document Type (Schema) <../creating_schema>` 134 | -------------------------------------------------------------------------------- /docs/gamedata/properties/property.rst: -------------------------------------------------------------------------------- 1 | Schema Property 2 | =============== 3 | 4 | Properties define which fields a document will contain. 5 | 6 | Name 7 | ^^^^ 8 | 9 | The **Name** of a property is used as an alternative identifier to the `Id` and is also used in generated source code as the name of the resulting field/property. Therefore, it must be a valid C-style identifier: it should start with a letter and include only Latin letters, digits, or underscores. 10 | 11 | Property names are also used as the name of the fields when storing or exporting data. It is recommended to use PascalCase and singular form for property names. 12 | 13 | Display Name 14 | ^^^^^^^^^^^^^ 15 | 16 | The **Display Name** is used in the UI and can contain any characters. There are no restrictions on alphabet or character set. 17 | 18 | Description 19 | ^^^^^^^^^^^^^ 20 | 21 | The **Description** helps other users understand the purpose of the property. It is shown in the UI and is also included as a documentation comment in the generated source code for the corresponding field/property. 22 | 23 | Sync Name 24 | ^^^^^^^^^^^^^ 25 | 26 | Some properties describe data types that are common across multiple schemas. 27 | For example, a ``PickList`` property might benefit from shared pick options used in several schemas. 28 | These synced properties are referred to as :doc:`Shared Properties `. 29 | 30 | Data Type 31 | ^^^^^^^^^^^^^ 32 | 33 | Each property has a data type, which determines what kind of data can be entered into the document's field, how it is stored on disk, and how it is represented at runtime. 34 | The editor UI will attempt to validate input based on the selected data type but does not strictly enforce it. 35 | At runtime, game data loading code will validate the data types and may fail if the document is malformed. 36 | 37 | Requirement 38 | ^^^^^^^^^^^^^ 39 | 40 | Specifies whether a value must be provided for the field. Possible values include: 41 | 42 | - **None** – No requirement to fill in the property. It can be absent from the document both on disk and at runtime. Typically represented as a nullable or optional type in supported source code languages. 43 | - **Not Null** – A value must be provided. For the ``Text`` data type, an empty string is considered a valid value. 44 | - **Not Empty** – The field must contain a non-empty value for ``Text`` or have at least one item for ``Collection`` data types. 45 | 46 | Uniqueness 47 | ^^^^^^^^^^^^^ 48 | 49 | Specifies uniqueness constraints for field values across documents. Useful to ensure certain values, such as names, are only used once. 50 | 51 | - **Unique** – The value must be unique across all documents. 52 | - **Unique In Collection** – The value must be unique within the scope of the current collection. 53 | 54 | Default Value 55 | ^^^^^^^^^^^^^ 56 | 57 | Defines the default value to use for newly created documents or to populate existing documents when a new required property is added. 58 | The default must be a properly formatted value consistent with the specified data type. 59 | 60 | Id Property 61 | ----------- 62 | 63 | Each document includes a required :doc:`Id ` property, which has specific constraints and must be present and valid. 64 | 65 | See also 66 | -------- 67 | 68 | - :doc:`Schema <../schemas/schema>` 69 | - :doc:`Id Property ` 70 | - :doc:`Shared Property ` 71 | - :doc:`All Data Types <../datatypes/list>` 72 | - :doc:`Creating Document Type (Schema) <../creating_schema>` -------------------------------------------------------------------------------- /docs/gamedata/properties/shared_property.rst: -------------------------------------------------------------------------------- 1 | Shared Property 2 | =============== 3 | 4 | A **Shared Property** is a :doc:`Schema <../schemas/schema>` property that syncs data type-related configuration with other properties of the same name across different schemas. When a shared property is modified in one schema, all other synced properties with the same shared name are updated accordingly. 5 | 6 | Shared properties can be unlinked (or "decoupled") at any time, converting them into independent, schema-specific properties. 7 | 8 | Replicated Parameters 9 | --------------------- 10 | 11 | Shared properties replicate a defined subset of configuration parameters between themselves: 12 | 13 | - Data Type 14 | - Default Value 15 | - Uniqueness 16 | - Requirement 17 | - Reference Type (for `Document`, `DocumentCollection`, `Reference`, and `ReferenceCollection` types) 18 | - Size 19 | - Specifications for `PickList`, `MultiPickList`, and `Formula` data types 20 | 21 | These parameters ensure consistency across schemas that use the same shared property. 22 | 23 | Impact on Generated Source Code 24 | ------------------------------- 25 | 26 | In cases where a property results in a distinct type in the generated source code—such as a `PickList` producing an ``enum``—the name of the shared property is used to derive the generated type name. 27 | 28 | For example: 29 | 30 | - A shared `PickList` property named ``Damage Type`` would generate: 31 | 32 | - `DamageType` enum in C#, Haxe, TypeScript 33 | - `EDamageType` enum in Unreal Engine C++ 34 | 35 | To customize this behavior, the `Generated Type Name` field of the property can be set manually to override the default naming convention. 36 | 37 | See also 38 | -------- 39 | 40 | - :doc:`Schema <../schemas/schema>` 41 | - :doc:`Property ` 42 | - :doc:`Id Property ` 43 | - :doc:`Shared Property ` 44 | - :doc:`All Data Types <../datatypes/list>` 45 | - :doc:`Creating Document Type (Schema) <../creating_schema>` -------------------------------------------------------------------------------- /docs/gamedata/publication.rst: -------------------------------------------------------------------------------- 1 | Publishing Game Data 2 | ==================== 3 | 4 | The publication process is a crucial step in preparing game data for usage inside the game. This process involves removing unused data, unused localization, and exporting data in a supported format - ``JSON`` or ``MessagePack``. This documentation will provide an overview of how to perform the publication process from both the project's dashboard user interface and the command-line interface (CLI). 5 | 6 | Using Project's Dashboard UI 7 | ----------------------------- 8 | 9 | To perform the publication process from the project's dashboard UI, please follow the steps below: 10 | 11 | 1. Navigate to the project's dashboard page. 12 | 2. Click on the *Publish* link. 13 | 3. Choose the format you want to export your data in - JSON or Message Pack. 14 | 4. Select the language(s) you want to publish. 15 | 5. Click on the *Finish* button to initiate the publication process. 16 | 6. Download the file. 17 | 18 | Using Command-Line Interface (CLI) 19 | ----------------------------------- 20 | 21 | To perform the publication process from the CLI, please follow the steps below: 22 | 23 | 1. Open the command-line interface. 24 | 2. Navigate to the game data's directory. 25 | 3. Use the ``DATA EXPORT`` command to publish the game data. 26 | 27 | Example 28 | -------- 29 | 30 | .. code-block:: bash 31 | 32 | dotnet charon DATA EXPORT --dataBase ".\gamedata.json" --mode publication --languages {en-US} --output ".\StreamingAssets\gamedata_pub.json" --outputFormat json 33 | 34 | - Use the ``--languages`` parameter to specify the language(s) you want to publish. Or omit parameter to publish all languages. 35 | - Use the ``--outputFormat`` parameter to specify the export format - ``json`` or ``msgpack``. 36 | 37 | See also 38 | -------- 39 | 40 | - :doc:`Generating Source Code ` 41 | - :doc:`Working with Source Code (C# 4.0) ` 42 | - :doc:`Working with Source Code (C# 7.3) ` 43 | - :doc:`Working with Source Code (TypeScript) ` 44 | - :doc:`Command Line Interface (CLI) <../advanced/command_line>` 45 | - :doc:`DATA EXPORT Command <../advanced/commands/data_export>` 46 | -------------------------------------------------------------------------------- /docs/gamedata/schemas/schema.rst: -------------------------------------------------------------------------------- 1 | Schema 2 | ====== 3 | 4 | A **Schema** defines the structure of a specific type of game data entity. It acts as a blueprint that outlines the fields (properties) associated with the entity, much like columns in a database table or cells in a spreadsheet. Schemas are central to organizing and modeling structured game data. 5 | 6 | Name 7 | ---- 8 | 9 | The **Name** of a schema is used as an alternative identifier to the `Id` and is also used in generated source code as the name of the resulting class. Therefore, it must be a valid C-style identifier: it should start with a letter and include only Latin letters, digits, or underscores. 10 | 11 | Schema names are also used as the name of the collection when storing or exporting data. It is recommended to use PascalCase and singular form for schema names. 12 | 13 | Display Name 14 | ------------ 15 | 16 | The **Display Name** is used in the UI and can contain any characters. There are no restrictions on alphabet or character set. 17 | 18 | Type 19 | ---- 20 | 21 | The **Type** setting defines how instances (documents) of this schema are created and managed: 22 | 23 | - **Normal**: Standard behavior. Documents can be created in the root collection, embedded in other documents, or may be absent entirely. 24 | - **Component**: These documents can only be embedded within other documents. They do not appear in the main navigation menu. 25 | - **Settings**: A singleton-style schema. Only one root-level document can exist, and it cannot be embedded in other documents. 26 | 27 | Display Text Template 28 | --------------------- 29 | 30 | The :doc:`Display Text Template ` defines how documents of this schema are presented in the UI when a textual representation is needed—e.g., in dropdowns, reference lists, or relationship views. 31 | 32 | Icon 33 | ---- 34 | 35 | The **Icon** is displayed next to the schema name in the navigation menu or selection dialogs within the UI. 36 | 37 | Description 38 | ----------- 39 | 40 | The **Description** helps other users understand the purpose of the schema. It is shown in the UI and is also included as a documentation comment in the generated source code for the corresponding class. 41 | 42 | Group 43 | ----- 44 | 45 | The **Group** defines the hierarchical path of the schema in the left-hand navigation menu. It behaves similarly to a folder path, with sections separated by the `/` character. 46 | 47 | Menu Visibility 48 | --------------- 49 | 50 | This flag determines whether the schema appears in the left-hand navigation menu in the UI. 51 | 52 | Id Generator 53 | ------------ 54 | 55 | The **Id Generator** setting defines how the :doc:`Id Property <../properties/id_property>` is managed for this schema. If set to `None`, the Id property must be configured manually. 56 | 57 | Properties 58 | ---------- 59 | 60 | A list of :doc:`Properties ` that define the fields associated with this schema. 61 | 62 | See also 63 | -------- 64 | 65 | - :doc:`Display Text Template ` 66 | - :doc:`Property <../properties/property>` 67 | - :doc:`Id Property <../properties/id_property>` 68 | - :doc:`Shared Property <../properties/shared_property>` 69 | - :doc:`Specification ` 70 | - :doc:`All Data Types <../datatypes/list>` 71 | - :doc:`Creating Document Type (Schema) <../creating_schema>` -------------------------------------------------------------------------------- /docs/gamedata/schemas/specification.rst: -------------------------------------------------------------------------------- 1 | Specification 2 | ============= 3 | 4 | The ``Specification`` field is a flexible extension point available on both :doc:`Schema ` and :doc:`Property <..\properties\property>` documents. It enables developers to attach additional metadata in a standardized format that can be used for custom logic in UI field editors, source code generation, or other tooling integrations. 5 | 6 | Overview 7 | -------- 8 | 9 | The ``Specification`` field stores a string formatted using the `application/x-www-form-urlencoded `_ standard (commonly referred to as `URLSearchParams `_ format). It contains key-value pairs separated by ampersands (`&`), where each key and value are URL-encoded. 10 | 11 | For example: 12 | 13 | .. code-block:: 14 | 15 | icon=table&group=Combat 16 | 17 | Use Cases 18 | --------- 19 | 20 | The `Specification` field is commonly used for: 21 | 22 | - **Schema metadata**: 23 | Define an icon, group behavior, or UI preferences: 24 | 25 | .. code-block:: 26 | 27 | icon=table&category=Gameplay&hideInMenu=true 28 | 29 | - **Property editor extensions**: 30 | Pass configuration values to custom editors: 31 | 32 | .. code-block:: 33 | 34 | colorFormat=RGB&alpha=true 35 | 36 | - **Source code generation**: 37 | Customize how types or methods are generated: 38 | 39 | .. code-block:: 40 | 41 | typeName=MyEnum&csAttribute=Obsolete 42 | 43 | Encoding Guide 44 | -------------- 45 | 46 | All keys and values must be properly URL-encoded to ensure compatibility with parsing libraries and avoid format-breaking characters. 47 | 48 | ### Encoding in JavaScript 49 | 50 | In any browser console or Node.js REPL: 51 | 52 | .. code-block:: js 53 | 54 | const params = new URLSearchParams({ 55 | icon: "sword", 56 | group: "Items and Stuff", 57 | noThumbnail: true 58 | }); 59 | console.log(params.toString()); 60 | // Output: icon=sword&group=Items%20and%20Stuff&noThumbnail=true 61 | 62 | 63 | ### Encoding in Excel 64 | 65 | To encode values manually using Excel formulas: 66 | 67 | - Build a key-value pair: 68 | 69 | .. code-block:: 70 | 71 | =ENCODEURL("noThumbnail") & "=" & ENCODEURL("true") 72 | 73 | 74 | - Combine multiple: 75 | 76 | .. code-block:: 77 | 78 | =ENCODEURL("icon") & "=" & ENCODEURL("sword") & "&" & ENCODEURL("group") & "=" & ENCODEURL("Items and Stuff") 79 | 80 | 81 | Best Practices 82 | -------------- 83 | 84 | - **Use lowercase or camelCase for keys** to ensure consistency. 85 | - **Avoid spaces or special characters** in keys; values should always be encoded. 86 | 87 | See also 88 | -------- 89 | 90 | - :doc:`Display Text Template ` 91 | - :doc:`Property <../properties/property>` 92 | - :doc:`Schema <../properties/property>` 93 | - :doc:`All Data Types <../datatypes/list>` 94 | - :doc:`Creating Document Type (Schema) <../creating_schema>` 95 | 96 | -------------------------------------------------------------------------------- /docs/gamedata/source_code_features.csv: -------------------------------------------------------------------------------- 1 | Feature,C#,TypeScript,C++ (UE),Haxe 2 | JSON Format,x,x,x,x 3 | MessagePack Format,x,x,x,x 4 | Language Switch,x,x,x,x 5 | Patching,x,x,x,x 6 | Formulas,x,x,, 7 | By Unique Value Indexing,x,,,x 8 | -------------------------------------------------------------------------------- /docs/gamedata/working_with_csharp_code_4_0.rst: -------------------------------------------------------------------------------- 1 | Working with Source Code (C# 4.0) 2 | ============================= 3 | 4 | .. warning:: 5 | This is deprecated code generator and shouldn't be used in new projects. 6 | 7 | Accessing game data during runtime is possible by utilizing the generated source code. 8 | 9 | This section provides examples using default class names, but it is possible to customize class names during the source code generation process. Additionally, this customization allows to avoid naming collisions with existing code. 10 | 11 | Loading Game Data 12 | ----------------- 13 | 14 | The following C# code creates ``GameData`` class and loads your game data into memory. 15 | 16 | .. code-block:: csharp 17 | 18 | using System.IO; 19 | 20 | var fileStream = File.OpenRead("gamedata.json"); 21 | var gameData = new GameData(fileStream, GameData.Format.Json); 22 | fileStream.Dispose(); 23 | 24 | The file ``gamedata.json`` could be :doc:`published ` game data or original database file (.gdjs or .gdmp). 25 | 26 | Accessing Documents 27 | ------------------- 28 | 29 | You can access your documents as a list: 30 | 31 | .. code-block:: csharp 32 | 33 | var characters = gameData.GetCharacters() // -> ReadOnlyList 34 | var characters = gameData.GetCharacters(onlyRoot: true) // -> ReadOnlyList 35 | 36 | Or you can access specific documents by their ``Id`` or *Unique* properties: 37 | 38 | .. code-block:: csharp 39 | 40 | var character = gameData.GetCharacter(characterId); // -> Character 41 | var character = gameData.GetCharacterByName(characterName); // -> Character 42 | 43 | ``Settings`` schemas are accessed by name: 44 | 45 | .. code-block:: csharp 46 | 47 | var resetTime = gameData.LootSettings.ResetTime; // -> TimeSpan 48 | 49 | Formulas 50 | -------- 51 | 52 | Formulas are executed with Invoke method: 53 | 54 | .. code-block:: csharp 55 | 56 | var reward = gameData.LootSettings.RewardFormula.Invoke() // -> int 57 | 58 | Formula's parameters are passed as arguments of ``Invoke`` method. 59 | 60 | Generated Code Extensions 61 | ------------------------- 62 | 63 | When generating source code for game data, the resulting C# classes are declared as `partial `_. This means that the classes can be extended by the programmer to add custom functionality. 64 | 65 | For example, let's say that you have generated a ``GameData`` class for your game data. This class contains properties and methods for accessing and manipulating the data. However, you want to add some custom functionality to this class, such as a method for getting specific documents by criteria. 66 | 67 | To do this, you can create a new C# file and declare a partial class with the same name as the generated ``GameData`` class. You can then define your custom method in this class, and it will be merged with the generated class at compile time. 68 | 69 | Here is an example of how this could look: 70 | 71 | .. code-block:: csharp 72 | // should be in same namespace as generated GameData class 73 | public partial class GameData { 74 | 75 | public IEnumerable GetFighterCharacters() { 76 | return this.GetCharacters().Where(character => character.Role == CharacterRole.Fighter); 77 | } 78 | 79 | } 80 | 81 | In this example, the ``GameData`` class is declared as partial, and two partial classes are defined with the same name: one generated by the source code generation process and one containing custom code added by the programmer. 82 | 83 | By using partial classes in this way, you can extend the functionality of the generated classes without modifying the generated code directly. This allows you to keep your custom code separate from the generated code, making it easier to maintain and update your game data classes over time. 84 | 85 | There is also two extension points on ``GameData`` class: 86 | 87 | .. code-block:: csharp 88 | 89 | partial void OnBeforeInitialize(); // Called after loading the data into lists and dictionaries and before processing references and marking documents read-only. 90 | partial void OnInitialize(); // Called after loading and prepping all data. 91 | 92 | See also 93 | -------- 94 | 95 | - :doc:`Generating Source Code ` 96 | - :doc:`GENERATE CSHARPCODE Command <../advanced/commands/generate_csharp_code>` -------------------------------------------------------------------------------- /docs/gamedata/working_with_haxe_code.rst: -------------------------------------------------------------------------------- 1 | Working with Source Code (Haxe) 2 | ================================= 3 | 4 | Accessing game data during runtime is possible by utilizing the generated source code. 5 | 6 | This section provides examples using default class names, but it is possible to customize class names during the source code generation process. Additionally, this customization allows to avoid naming collisions with existing code. 7 | 8 | Loading Game Data 9 | ----------------- 10 | 11 | The following Haxe code creates ``GameData`` class and loads your game data into memory. 12 | 13 | .. code-block:: haxe 14 | 15 | import GameData; 16 | import Formatters; 17 | import haxe.io.Path; 18 | import sys.io.File; 19 | 20 | var input = File.read("RpgGameData.gdjs"); // or .json 21 | var options = new GameDataLoadOptions(); 22 | options.format = GameDataFormat.Json; 23 | options.leaveInputsOpen = false; 24 | // options.patches <-- put patches here 25 | var gameData = new GameData(input, options); 26 | 27 | The file ``RpgGameData.gdjs`` could be :doc:`published ` game data or original database file (.gdjs or .gdmp). 28 | 29 | Accessing Documents 30 | ------------------- 31 | 32 | You can access your documents as a list: 33 | 34 | .. code-block:: haxe 35 | 36 | var allHeroes = gameData.heroesAll.list // -> ReadOnlyArray 37 | var heroes = gameData.heroes.list // -> ReadOnlyArray 38 | 39 | Or you can access specific documents by their ``id`` or *Unique* properties: 40 | 41 | .. code-block:: haxe 42 | using GameData; // load byName() and other extension methods 43 | 44 | var heroById = gameData.heroesAll.get(heroId); // -> Hero 45 | var heroByName = gameData.heroesAll.byName().get(heroName); // -> Hero 46 | 47 | ``Settings`` schemas are accessed by name: 48 | 49 | .. code-block:: haxe 50 | 51 | var startingHeroes = gameData.startingSet.heroes; // -> ReadOnlyArray 52 | 53 | Formulas 54 | -------- 55 | 56 | Formulas are currently not supported. 57 | 58 | Extension of Generated Code 59 | ------------------------- 60 | 61 | Customizing Metadata 62 | ^^^^^^^^^^^^^^^^^^^^ 63 | 64 | You can append additional `metadata `_ to the generated classes and their properties by modifying the ``Specification`` field of the related schema or property. 65 | 66 | metadata annotations are specified using the ``haxeAttribute`` key in the ``Specification`` string, which uses the ``application/x-www-form-urlencoded`` format. 67 | 68 | To help construct the correct value, you can use a spreadsheet formula (e.g., in Excel or Google Sheets): 69 | 70 | .. code-block:: none 71 | 72 | # Place your attribute in cell A1 73 | =TEXTJOIN("&", 1, IF(ISBLANK(A1), "", "&haxeAttribute=" & ENCODEURL(A1))) 74 | 75 | Alternatively, use JavaScript to generate the encoded string: 76 | 77 | .. code-block:: javascript 78 | 79 | const params = new URLSearchParams(); 80 | params.append("haxeAttribute", ":deprecated"); 81 | console.log(params.toString()); 82 | // → haxeAttribute=%3Adeprecated 83 | 84 | After obtaining the encoded string, append it to the existing ``Specification`` value. 85 | 86 | Example: 87 | 88 | .. code-block:: none 89 | 90 | # Original Specification value: 91 | icon=material&group=Metadata 92 | 93 | # New attribute to add: 94 | haxeAttribute=%3Adeprecated 95 | 96 | # Final Specification value: 97 | icon=material&group=Metadata&haxeAttribute=%3Adeprecated 98 | 99 | You can add multiple metadata annotations by including multiple ``haxeAttribute`` keys: 100 | 101 | .. code-block:: none 102 | 103 | haxeAttribute=broken&haxeAttribute=range%281%2C+2%29 104 | 105 | These metadata annotations will be emitted directly into the generated Haxe code, attached to the appropriate class or property. 106 | 107 | See also 108 | -------- 109 | 110 | - :doc:`Generating Source Code ` 111 | - :doc:`GENERATE HAXE Command <../advanced/commands/generate_haxe_code>` -------------------------------------------------------------------------------- /docs/gamedata/working_with_type_script_code.rst: -------------------------------------------------------------------------------- 1 | Working with Source Code (Type Script) 2 | ============================= 3 | 4 | Accessing game data during runtime is possible by utilizing the generated source code. 5 | 6 | This section provides examples using default class names, but it is possible to customize class names during the source code generation process. Additionally, this customization allows to avoid naming collisions with existing code. 7 | 8 | Loading Game Data 9 | ----------------- 10 | 11 | The following Type Script code creates ``GameData`` class and loads your game data into memory. 12 | 13 | .. code-block:: js 14 | 15 | import { GameData } from './game.data'; 16 | import { Formatters } from './formatters'; 17 | 18 | // Node.js 19 | import { readFileSync } from 'fs'; 20 | const gameDataStream = readFileSync(gameDataFilePath); 21 | 22 | // Blob or File 23 | const gameDataStream = gameDataFileBlob.arrayBuffer(); 24 | 25 | // XMLHttpRequest (XHR) 26 | // gameDataRequest.responseType -> "arraybuffer" 27 | const gameDataStream = gameDataRequest.response; 28 | 29 | const gameData = new GameData(gameDataStream, { 30 | format: Formatters.GameDataFormat.Json, 31 | // patches: [patchStream1, patchStream2, ...] 32 | }); 33 | 34 | The content of ``gameDataStream`` could be :doc:`published ` game data or original database file (.gdjs or .gdmp). 35 | 36 | Accessing Documents 37 | ------------------- 38 | 39 | You can access your documents as a list: 40 | 41 | .. code-block:: js 42 | 43 | let heroes = gameData.heroesAll; // all heroes from all documents -> readonly Hero[] 44 | let heroes = gameData.heroes; // heroes only from root collection -> readonly Hero[] 45 | 46 | Or you can access specific documents by their ``Id`` or *Unique* properties: 47 | 48 | .. code-block:: js 49 | 50 | let hero = gameData.heroesAll.find(heroId); // -> Hero | undefined 51 | let hero = gameData.heroesAll.withOtherKey('Name').find(heroName); // -> Hero | undefined 52 | 53 | ``Settings`` schemas are accessed by name: 54 | 55 | .. code-block:: js 56 | 57 | let resetTime = gameData.lootSettings.resetTime; // -> TimeSpan 58 | 59 | Formulas 60 | -------- 61 | 62 | Formulas inherit the ``Function`` type and can be invoked as-is or with ``invoke`` method: 63 | 64 | .. code-block:: js 65 | 66 | var reward = gameData.lootSettings.rewardFormula() // -> number 67 | // or 68 | var reward = gameData.lootSettings.rewardFormula.invoke() // -> number 69 | 70 | Formula's parameters are passed as arguments of ``invoke`` method. 71 | 72 | Any non-game data related types are imported from ```formula.known.types.ts``, which should be created by the developer and have all required types exported. 73 | Here is an example of a ``formula.known.types.ts`` file: 74 | 75 | .. code-block:: js 76 | 77 | import { MyFormulaContext } from '../my.formula.context'; 78 | 79 | // example of MyFormulaContext type. 80 | export MyFormulaContext; 81 | 82 | // example of Assets.Scripts.CheckContext. 83 | export namespace Assets.Scripts { 84 | export class CheckContext { 85 | myField: string; 86 | } 87 | } 88 | 89 | 90 | Extension of Generated Code 91 | ------------------------- 92 | 93 | Customizing Decorators 94 | ^^^^^^^^^^^^^^^^^^^^^^ 95 | 96 | You can append additional `TypeScript Decorators `_ to the generated classes and their properties by modifying the ``Specification`` field of the related schema or property. 97 | 98 | Decorators are specified using the ``tsAttribute`` key in the ``Specification`` string, which uses the ``application/x-www-form-urlencoded`` format. 99 | 100 | To help construct the correct value, you can use a spreadsheet formula (e.g., in Excel or Google Sheets): 101 | 102 | .. code-block:: none 103 | 104 | # Place your attribute in cell A1 105 | =TEXTJOIN("&", 1, IF(ISBLANK(A1), "", "&tsAttribute=" & ENCODEURL(A1))) 106 | 107 | Alternatively, use JavaScript to generate the encoded string: 108 | 109 | .. code-block:: javascript 110 | 111 | const params = new URLSearchParams(); 112 | params.append("tsAttribute", "deprecated(\"Value is deprecated\")"); 113 | console.log(params.toString()); 114 | // → tsAttribute=deprecated%28%22Value+is+deprecated%22%29 115 | 116 | After obtaining the encoded string, append it to the existing ``Specification`` value. 117 | 118 | Example: 119 | 120 | .. code-block:: none 121 | 122 | # Original Specification value: 123 | icon=material&group=Metadata 124 | 125 | # New attribute to add: 126 | tsAttribute=deprecated%28%22Value+is+deprecated%22%29 127 | 128 | # Final Specification value: 129 | icon=material&group=Metadata&tsAttribute=deprecated%28%22Value+is+deprecated%22%29 130 | 131 | You can add multiple attributes by including multiple ``tsAttribute`` keys: 132 | 133 | .. code-block:: none 134 | 135 | tsAttribute=@Input&tsAttribute=range%281%2C+2%29 136 | 137 | These attributes will be emitted directly into the generated TypeScript code, attached to the appropriate class or property. 138 | 139 | 140 | See also 141 | -------- 142 | 143 | - :doc:`Generating Source Code ` 144 | - :doc:`GENERATE TYPESCRIPTCODE Command <../advanced/commands/generate_typescript_code>` -------------------------------------------------------------------------------- /docs/gamedata/working_with_uecpp_code_.rst: -------------------------------------------------------------------------------- 1 | Working with Source Code (UE C++) 2 | ================================= 3 | 4 | .. warning:: 5 | The source code for Unreal Engine requires a `plugin `_ to be installed to function. If you get compilation errors, make sure the plugin is `installed and enabled <../unreal_engine/overview>`_. 6 | 7 | Accessing game data during runtime is possible by utilizing the generated source code. 8 | 9 | This section provides examples using default class names, but it is possible to customize class names during the source code generation process. Additionally, this customization allows to avoid naming collisions with existing code. 10 | 11 | Loading Game Data 12 | ----------------- 13 | 14 | The following C++ code creates ``UGameData`` class and loads your game data into memory. 15 | 16 | .. code-block:: cpp 17 | 18 | IFileManager& FileManager = IFileManager::Get(); 19 | 20 | const FString GameDataFilePath = TEXT("./RpgGameData.gdjs"); // or .json 21 | const TUniquePtr GameDataStream = TUniquePtr(FileManager.CreateFileReader(*GameDataFilePath, EFileRead::FILEREAD_None)); 22 | 23 | UGameData* GameData = NewObject(); 24 | 25 | FGameDataLoadOptions Options; 26 | Options.Format = EGameDataFormat::Json; 27 | // Options.Patches.Add(PatchStream1); 28 | // Options.Patches.Add(PatchStream2); 29 | // ... 30 | 31 | if (!GameData->TryLoad(GameDataStream.Get(), Options)) 32 | { 33 | // Handle failure 34 | } 35 | 36 | The file ``RpgGameData.gdjs`` could be :doc:`published ` game data or original database file (.gdjs or .gdmp). 37 | 38 | Accessing Documents 39 | ------------------- 40 | 41 | You can access your documents as a list: 42 | 43 | .. code-block:: cpp 44 | 45 | auto AllHeroes = GameData->AllHeroes // -> TMap 46 | auto Heroes = GameData->Heroes // -> TMap 47 | 48 | ``Settings`` schemas are accessed by name: 49 | 50 | .. code-block:: cpp 51 | 52 | auto StartingHeroes = GameData->StartingSet.Heroes; // -> TMap 53 | 54 | Formulas 55 | -------- 56 | 57 | Formulas are currently not supported. 58 | 59 | Extension of Generated Code 60 | ------------------------- 61 | 62 | Customizing Metadata 63 | ^^^^^^^^^^^^^^^^^^^^^^ 64 | 65 | You can append additional or replace existing `macro `_ to the generated classes and their properties by modifying the ``Specification`` field of the related schema or property. 66 | 67 | Metadata annotations are specified using the ``uecppAttribute`` key in the ``Specification`` string, which uses the ``application/x-www-form-urlencoded`` format. 68 | 69 | To help construct the correct value, you can use a spreadsheet formula (e.g., in Excel or Google Sheets): 70 | 71 | .. code-block:: none 72 | 73 | # Place your attribute in cell A1 74 | =TEXTJOIN("&", 1, IF(ISBLANK(A1), "", "&uecppAttribute=" & ENCODEURL(A1))) 75 | 76 | Alternatively, use JavaScript to generate the encoded string: 77 | 78 | .. code-block:: javascript 79 | 80 | const params = new URLSearchParams(); 81 | params.append("uecppAttribute", "UPROPERTY(EditAnywhere, Meta = (Bitmask))"); 82 | console.log(params.toString()); 83 | // → uecppAttribute=UPROPERTY%28EditAnywhere%2C+Meta+%3D+%28Bitmask%29%29 84 | 85 | After obtaining the encoded string, append it to the existing ``Specification`` value. 86 | 87 | Example: 88 | 89 | .. code-block:: none 90 | 91 | # Original Specification value: 92 | icon=material&group=Metadata 93 | 94 | # New attribute to add: 95 | uecppAttribute=UCLASS%28BlueprintType%29 96 | 97 | # Final Specification value: 98 | icon=material&group=Metadata&uecppAttribute=UCLASS%28BlueprintType%29 99 | 100 | These metadata annotations will be emitted directly into the generated C++ code, attached to the appropriate class or property. 101 | 102 | 103 | See also 104 | -------- 105 | 106 | - :doc:`Generating Source Code ` 107 | - :doc:`GENERATE UECPP Command <../advanced/commands/generate_uecpp_code>` 108 | -------------------------------------------------------------------------------- /docs/glossary.rst: -------------------------------------------------------------------------------- 1 | Glossary 2 | ======== 3 | 4 | Game Data 5 | The static information for the game, such as items, quests, dialogues, etc., is stored as game data. Schemas are also included to organize and structure game data. 6 | 7 | Schema 8 | A schema is a description of the structure for documents in game data. It defines the properties and structure of each document in the game data. 9 | 10 | Schema Property 11 | A part of a schema that defines a specific property or attribute of a document in the game data. 12 | 13 | Formula 14 | A property data type in a schema for a C# expression that can be executed at runtime to calculate a value for a field. 15 | 16 | Reference 17 | A property data type in a schema for a pointer to another document. 18 | 19 | Document 20 | A specific instance of a schema in the game data. It represents a single item or entity in the game, such as an item, quest, or dialogue. 21 | 22 | Field 23 | A named part of a document that holds a specific value. 24 | 25 | Source Code 26 | The code generated by Charon that represents the game data. This code can be used to load the game data at runtime. 27 | 28 | Metadata 29 | All the schemas and relations between them. This data is used by Charon to generate the source code for the game data. 30 | 31 | Workspace 32 | In the web application, the workspace is the place where users can manage their projects and subscription. 33 | 34 | Project 35 | In the web application, a project is a container for organizing related game data. It can contain multiple branches. 36 | 37 | Branch 38 | In the web application, a branch is a specific variant of game data within a project. It can be used to manage different versions or stages of the game data. 39 | 40 | API Key 41 | A unique identifier generated for a user in the User's Profile "API Keys" section, which can be used to access the REST API and CLI for various operations. It allows for automation of game build processes, such as pushing game data to local GIT repositories. 42 | 43 | Publication 44 | The process of exporting game data in a format that can be loaded into the game. -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | Overview 2 | ======== 3 | 4 | Charon is a powerful data-driven game development tool designed to streamline the creation and management of static game data within your game. 5 | 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/Unreal Engine/Browser environment. 6 | 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. 7 | Charon also offers support for working with text in multiple languages, with easy loading and unloading of translated text. 8 | 9 | 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 :doc:`standalone ` application, :doc:`web ` application, :doc:`Unity ` plugin and :doc:`Unreal Engine ` plugin. 10 | 11 | **TLDR** Charon is an in-game database for your game, replacing spreadsheets or config files. 12 | 13 | Why Choose Charon? 14 | ------------------ 15 | 16 | Charon replaces traditional spreadsheets or config files with an in-game database, 17 | offering a structured and efficient way to manage game data. It allows developers to focus on creating engaging gameplay 18 | experiences without worrying about the technical details of data management. 19 | 20 | Is It Free? 21 | ----------- 22 | 23 | The offline version, :doc:`CLI ` and plugins are completely free and have no restrictions. 24 | They are distributed under a free license and allow you to distribute tools along with the game for modding games. 25 | 26 | The online version, which allows working in large teams on shared game data, requires a subscription. 27 | 28 | What is Charon 29 | -------------- 30 | 31 | It is a .NET 8 console application that can be used as a :doc:`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 :doc:`Unity ` and :doc:`Unreal Engine ` that provide a more integrated experience while using Charon. 32 | As with any modern .NET application, it can be launched as is on Windows, macOS and Linux and via `dotnet` tool. 33 | 34 | 35 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/editor_screenshot.png 36 | :width: 600 37 | :alt: Charon UI 38 | 39 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/dashboard.png 40 | :width: 256 41 | :alt: Charon Dashboard 42 | 43 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/document_collection.png 44 | :width: 256 45 | :alt: Charon Documents 46 | 47 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/document_form.png 48 | :width: 256 49 | :alt: Charon Document Form 50 | 51 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/documents_import.png 52 | :width: 256 53 | :alt: Charon Document Import 54 | 55 | Further reading 56 | --------------- 57 | 58 | .. toctree:: 59 | :caption: Unreal Engine Quick Start 60 | :titlesonly: 61 | :glob: 62 | 63 | /unreal_engine/overview 64 | /unreal_engine/* 65 | 66 | 67 | .. toctree:: 68 | :caption: Unity Quick Start 69 | :titlesonly: 70 | :glob: 71 | 72 | /unity/overview 73 | /unity/* 74 | 75 | .. toctree:: 76 | :caption: Standalone Quick Start 77 | :titlesonly: 78 | :glob: 79 | 80 | /standalone/overview 81 | /standalone/* 82 | 83 | .. toctree:: 84 | :caption: Web Quick Start 85 | :titlesonly: 86 | :glob: 87 | 88 | /web/overview 89 | /web/* 90 | 91 | .. toctree:: 92 | :caption: Working with Game Data 93 | :titlesonly: 94 | :glob: 95 | 96 | /gamedata/* 97 | 98 | .. toctree:: 99 | :caption: Advanced Features 100 | :titlesonly: 101 | :glob: 102 | 103 | /advanced/* 104 | /advanced/extensions/overview 105 | 106 | .. toctree:: 107 | :caption: Reference 108 | :titlesonly: 109 | 110 | /faq 111 | /glossary -------------------------------------------------------------------------------- /docs/readme.md: -------------------------------------------------------------------------------- 1 | [Charon Documentation at GitHub Pages](https://gamedevware.github.io/charon/) 2 | -------------------------------------------------------------------------------- /docs/unity/charon_cli.rst: -------------------------------------------------------------------------------- 1 | CharonCli Overview 2 | ================== 3 | 4 | The `CharonCli `_ class provides a convenient interface for running ``dotnet charon`` command-line operations. It simplifies interactions with the Charon tool, enabling developers to manage game data, automate workflows, and integrate with Unity projects. Below is an overview of its methods grouped by purpose. 5 | 6 | Game Data Management 7 | -------------------- 8 | 9 | - **InitGameDataAsync**: Initializes a GameData file. 10 | - **CreateDocumentAsync**: Creates a document in the specified GameData URL. 11 | - **UpdateDocumentAsync**: Updates a document in the specified GameData URL. 12 | - **DeleteDocumentAsync**: Deletes a document in the specified GameData URL (by document or ID). 13 | - **FindDocumentAsync**: Finds a document in the specified GameData URL by ID. 14 | - **ListDocumentsAsync**: Lists documents in the specified GameData URL with optional filters and sorting. 15 | 16 | Import and Export 17 | ----------------- 18 | 19 | - **ImportAsync**: Imports documents grouped by schema into a specified GameData URL. 20 | - **ImportFromFileAsync**: Imports documents from a file into a specified GameData URL. 21 | - **ExportAsync**: Exports documents from a GameData URL. 22 | - **ExportToFileAsync**: Exports documents from a GameData URL to a file. 23 | 24 | Localization (I18N) 25 | ------------------- 26 | 27 | - **I18NImportAsync**: Imports translated documents grouped by schema into a specified GameData URL. 28 | - **I18NImportFromFileAsync**: Imports translated documents from a file into a specified GameData URL. 29 | - **I18NExportAsync**: Exports documents for localization from a GameData URL. 30 | - **I18NExportToFileAsync**: Exports documents for localization from a GameData URL to a file. 31 | - **I18NAddLanguageAsync**: Adds translation languages to a GameData URL. 32 | 33 | Patching and Backup 34 | ------------------- 35 | 36 | - **CreatePatchAsync**: Compares documents in two GameData URLs and creates a patch representing the difference. 37 | - **CreatePatchToFileAsync**: Compares documents in two GameData URLs and saves the patch to a file. 38 | - **ApplyPatchAsync**: Applies a patch to a specified GameData URL. 39 | - **ApplyPatchFromFileAsync**: Applies a patch from a file to a specified GameData URL. 40 | - **BackupAsync**: Backs up game data with all documents and metadata. 41 | - **BackupToFileAsync**: Backs up game data to a file with all documents and metadata. 42 | - **RestoreAsync**: Restores game data from a backup. 43 | - **RestoreFromFileAsync**: Restores game data from a backup file. 44 | 45 | Validation and Code Generation 46 | ------------------------------ 47 | 48 | - **ValidateAsync**: Validates all documents in a GameData URL and returns a report with issues. 49 | - **GenerateCSharpCodeAsync**: Generates C# source code for loading game data into a game's runtime. 50 | - **DumpTemplatesAsync**: Dumps T4 code generation templates into a specified directory. 51 | 52 | Tool Utilities 53 | -------------- 54 | 55 | - **GetVersionAsync**: Gets the version number of the Charon tool executable. 56 | - **GetGameDataToolVersionAsync**: Gets the version of the Charon tool used to create a GameData URL. 57 | - **RunCharonAsync**: Runs a specified command with the Charon tool. 58 | - **RunT4Async**: Processes T4 templates using the ``dotnet-t4`` command-line tool. 59 | 60 | See also 61 | -------- 62 | 63 | - :doc:`Unity Plugin Overview ` 64 | - `CharonCli class `_ 65 | - `Examples of CharonCli class `_ 66 | -------------------------------------------------------------------------------- /docs/unity/migrating_from_legacy_version.rst: -------------------------------------------------------------------------------- 1 | Migration from Legacy Version (Before 2025.1.*) 2 | =============================================== 3 | 4 | .. warning:: 5 | **Before proceeding with the migration, ensure your project is under a source control system (e.g., Git) or that a full backup of your project has been created.** 6 | Migration involves modifying and deleting files, and having a backup or version control ensures you can recover in case of unexpected issues. 7 | 8 | Install the package with the new version of the plugin via the `Unity Asset Store `_ or using `OpenUPM `_ (recommended). After installing plugin package you have two options: 9 | 10 | Automated Migration 11 | ------------------- 12 | 13 | A window will appear offering to perform the migration automatically. 14 | 15 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/unity_migrate_window.png 16 | :width: 498 17 | :alt: Unity Editor Migrate Plugin 18 | 19 | 1. Click the **Migrate** button and wait for the process to complete. 20 | 2. Once the migration is finished, close the window if everything is successful. 21 | 3. If an error occurs, check the **Console** window for details and consider using the *Manual Migration* approach. 22 | 23 | Manual Migration 24 | ------------------- 25 | 26 | To migrate manually, you will need to remove the old plugin, convert, and configure the game data files: 27 | 28 | 1. Navigate to the ``Assets/Editor/GameDevWare.Charon`` folder and delete it. 29 | 2. Temporarily move all **.gdjs** and **.gdmp** files from ``Assets/StreamingAssets/`` to ``Assets/``. 30 | 3. Select each **.gdjs** or **.gdmp** file and click the **Reimport** button in the **Inspector** window. 31 | 4. Replace the old **.asset** file with the newly generated one. If the file did not exist previously, place it anywhere within the boundaries of the **.asmdef** file. 32 | 5. Replace the old source code files (**.cs**) with the newly generated ones. 33 | 34 | .. warning:: 35 | Preserve the original **.meta** files for **.cs** and **.asset** assets to maintain Unity resource associations and links. 36 | 37 | See also 38 | -------- 39 | 40 | - :doc:`Unity Plugin Overview ` -------------------------------------------------------------------------------- /docs/unity/migrating_to_web.rst: -------------------------------------------------------------------------------- 1 | Migrating to Web Application 2 | ============================ 3 | 4 | To migrate to the https://charon.live, you can do it through a `backup <../web/migrating_to_web>` or through the "Connection" mechanism. 5 | 6 | In short: you need to create an empty project in at https://charon.live, in Unity Editor in Inspector window click **Connect**, and specify that you want to upload data to the https://charon.live. 7 | 8 | Migration with Connection 9 | ------------------------- 10 | 11 | Be sure to back up your local data before making any connections. 12 | 13 | 1. At https://charon.live: on the Home screen, click on **Create Project**. 14 | 2. Specify the project name, tags, and script language. 15 | 3. Click the **Create** button. 16 | 4. In the Unity Editor: select your game data **.asset** file in the **Project** window. 17 | 5. In the **Inspector** window, expand **** foldout, click **Connect** button. 18 | 6. In the dialog that opens, click on the **Profile → API Keys** link. 19 | 7. At https://charon.live: a page of your profile on the *API Keys* management page should have opened in your browser. 20 | 8. Click **Create API Key...** button. 21 | 9. Fill in the name and expiration time, then click the **Create** button. 22 | 10. Click the **Copy** button in the list of keys next to the newly created key labeled "New!". 23 | 11. In the Unity Editor: paste the *API Key* into the corresponding field in the **Connect Game Data** window. 24 | 12. Check the *Upload local data...* checkbox, it is only available when the selected *Project* is empty and does not contain any data. 25 | 13. Click the **Upload** button". 26 | 14. Close **Connect Game Data** window 27 | 28 | See also 29 | -------- 30 | 31 | - :doc:`Basics ` 32 | - `Charon Website `_ -------------------------------------------------------------------------------- /docs/unreal_engine/creating_game_data.rst: -------------------------------------------------------------------------------- 1 | How to Create Game Data File 2 | ============================== 3 | 4 | To create a new game data file within the Unreal Engine Editor, open the **Content Drawer**, right-click in the desired folder, and select in the **Create Advanced Assets** section **Miscellaneous → Game Data** menu option. 5 | Name your game data file and proceed according to the instructions in the dialog window that appears. 6 | 7 | Step By Step 8 | ------------ 9 | 10 | 1. **Open Content Drawer:** Open the *Content Drawer* window in the Unreal Engine Editor. 11 | 2. **Select Folder:** Right-click in the desired folder where you want to create the game data file. 12 | 3. **Create Game Data:** Navigate to **Create Advanced Assets → Miscellaneous → Game Data** from the context menu. 13 | 4. **Name the File:** In the *Content Drawer* window that appears, enter a name for your game data file. 14 | 5. **Check for Errors:** Ensure there are no error messages in the dialog window that opens, then press *Next*. 15 | 6. **Wait for Module Generation:** Allow time for the new module to be generated, watching the wizard in the dialog proceed to the next step automatically. 16 | 7. **Review Summary:** Check the summary and verify there are no suspicious errors in the *Output Log* window. 17 | 8. **Recompile C++ Code:** Use your IDE of choice to recompile the C++ code. Restart Unreal Engine Editor if needed. 18 | 9. **Import Game Data:** Reopen the *Content Drawer* window and click the **Import** button. 19 | 10. **Select .gdjs File:** Locate and select the *.gdjs* game data file you named in step 4, then click *Ok*. 20 | 11. **Choose Game Data Class:** Select the *Game Data* class, which should match the game data file name. If it's not listed, return to step 7. 21 | 12. **Save .uasset File:** Save the newly created *.uasset* file after completing the import process. 22 | 23 | Throubleshooting 24 | ---------------- 25 | Game data creation or code generation/compilation may encounter issues under certain circumstances: 26 | 27 | **Insufficient File System Rights or File Creation Errors** 28 | - **Problem**: Lack of sufficient rights to the OS file system, or errors during file creation (e.g., file name too long, antivirus block). 29 | - **Solution**: Check the *Output Log* window for errors or the most recent log file in ``\Intermediate\Charon\logs`` and attempt to resolve them. 30 | 31 | **Class Name Collision Within Project** 32 | - **Solution 1** (Game Data Class Name Collision): Delete the newly created **.gdjs** game data file and the generated module. Then, start over with a new name and clean your ``.Target.cs`` files from the generated module name. 33 | - **Solution 2** (Schema Class Name Collision): Open the game data in another editor (Online, Standalone), rename the schema, and try again. 34 | 35 | **No Game Data Class in Import Window** 36 | - **Problem**: The generated game data module is not being compiled. 37 | - **Solution**: Ensure it's added to your ``.Target.cs`` and ``Editor.Target.cs`` files as an extra module. 38 | If missing, include following expression in both target files: 39 | 40 | .. code-block:: cs 41 | 42 | ExtraModuleNames.Add(""); 43 | 44 | 45 | Additionally, verify that your **.uproject** file includes the generated module definition. If it's absent, add the following module definition to the **Modules** list: 46 | 47 | .. code-block:: json 48 | 49 | { 50 | "Name": "", 51 | "Type": "Runtime", 52 | "LoadingPhase": "Default" 53 | } 54 | 55 | See also 56 | -------- 57 | 58 | - :doc:`Basic Navigation and User Interface Overview <../gamedata/basics>` 59 | - :doc:`Creating Document Type (Schema) <../gamedata/creating_schema>` 60 | - :doc:`Filling Documents <../gamedata/filling_documents>` 61 | - :doc:`Frequently Asked Questions (FAQ) <../faq>` 62 | - :doc:`Glossary <../glossary>` 63 | -------------------------------------------------------------------------------- /docs/web/cli_access_to_web_project.rst: -------------------------------------------------------------------------------- 1 | CLI Access to charon.live 2 | ========================= 3 | 4 | The web version of the Charon provides a :doc:`REST API ` and :doc:`CLI <../advanced/command_line>` for accessing and modifying game data. To access the API, users need to generate an ``API Key`` in the *API Keys* section of their *User Profile*. 5 | 6 | With the API Key, Charon can easily be integrated into existing game development workflows. For example, the API Key can be used to export game data from the web into a local GIT repository 7 | 8 | Step By Step 9 | ------------ 10 | 11 | To generate an API Key: 12 | 13 | 1. Navigate to the *API Keys* section and click on the *Generate API Key...* button. 14 | 2. Copy the generated ``API Key``. 15 | 3. Use the ``API Key`` in `the `Authenticate`` header to access the REST API or in the ``--credentials`` parameter of the CLI. 16 | 17 | See also 18 | -------- 19 | 20 | - :doc:`Command Line Interface (CLI) <../advanced/command_line>` 21 | - :doc:`Migrating to Web ` 22 | - :doc:`REST API ` 23 | - :doc:`DATA EXPORT Command <../advanced/commands/data_export>` 24 | - :doc:`DATA IMPORT Command <../advanced/commands/data_import>` 25 | - :doc:`GENERATE CSHARPCODE Command <../advanced/commands/generate_csharp_code>` -------------------------------------------------------------------------------- /docs/web/migrating_to_web.rst: -------------------------------------------------------------------------------- 1 | Migrating to Web Application 2 | ============================ 3 | 4 | To migrate to the web application, you only need to backup your game data in your current editor and restore it in the web application. 5 | 6 | In short: project settings include a backup and restore feature. You make a backup in one place, and you can restore it in another. This is how you can transfer game data to another project. 7 | 8 | Backup Data Step by Step 9 | ------------------------- 10 | 11 | 1. Open your game data in the editor (Standalone, Unity ...) 12 | 2. In the bottom left corner, click on the gear icon "Settings" 13 | 3. In the left menu, select "Backup" 14 | 4. On the backup management page, click the "Backup" button 15 | 5. Choose "File" as the destination to save the backup and click "Next" 16 | 6. On the "Format" step, select "JSON" and click "Backup" 17 | 7. On the "Summary" step, click the link with a file name like ``backup_2023_11_10_11_27.json`` and save it to your computer. 18 | 19 | Restoring Backup in the Web Application 20 | -------------------------------------- 21 | 22 | 1. On the Home screen, click on "Create Project" 23 | 2. Specify the project name, tags, and script language 24 | 3. Click the "Create" button 25 | 4. In the left menu, select "Backup" 26 | 5. On the backup management page, click the "Restore" button 27 | 6. Choose "File" as the source of the restore and click "Next" 28 | 7. Select the input file, the one you have after the backup, such as ``backup_2023_11_10_11_27.json``, and click "Restore" 29 | 8. Done 30 | 31 | Any data that was in this project at the time before the restore will be lost. 32 | 33 | See also 34 | -------- 35 | 36 | - :doc:`Basic Navigation and User Interface Overview <../gamedata/basics>` 37 | - :doc:`Publication of Game Data <../gamedata/publication>` 38 | - :doc:`Generating Source Code <../gamedata/generating_source_code>` 39 | - :doc:`Frequently Asked Questions (FAQ) <../faq>` 40 | - :doc:`Glossary <../glossary>` -------------------------------------------------------------------------------- /docs/web/overview.rst: -------------------------------------------------------------------------------- 1 | Web Application Overview 2 | ======================== 3 | 4 | The web version of the Charon provides a collaborative work environment where game designers can work together to create engaging gameplay experiences. 5 | The core concepts of collaborative work include workspaces and projects. 6 | A workspace is a virtual location where projects are located. The subscription and all limitations are bound to the workspace, 7 | meaning that all projects within the workspace are subject to the same subscription and limitations. 8 | 9 | A project is a virtual location for storing game data, localization settings, backups, branches, and members. When a project is created, 10 | the user becomes its owner and can invite other members to join. 11 | 12 | .. image:: https://raw.githubusercontent.com/gamedevware/charon/main/docs/assets/editor_screenshot.png 13 | :width: 800 14 | :alt: Charon editor UI 15 | 16 | Starting with a new Project 17 | ------------------------- 18 | 19 | 1. Visit the `charon.live `_ website and click on the *Register* button to create a new account. 20 | 2. Fill out the registration form with your desired username and password, and click on the "Create" button to create your account. 21 | 3. After successfully logging in, you will be directed to the workspace page. 22 | 4. If you're a new user, the workspace page will be empty, with no projects listed. Click on the *Create project* button to create your first project. 23 | 5. On the "Create Project" page, fill in the name of your project and any other basic information you want to include, and click on the "Create" button to create your project. 24 | 6. After creating the project, you'll be redirected to the project's dashboard page, which provides an overview of the project and allows you to start modelling game data. 25 | 26 | See also 27 | -------- 28 | 29 | - `Charon Website `_ 30 | - :doc:`CLI Access to Web Project ` 31 | - :doc:`Migrating to Web Application ` 32 | - :doc:`Basic Navigation and User Interface Overview <../gamedata/basics>` 33 | - :doc:`Creating Document Type (Schema) <../gamedata/creating_schema>` 34 | - :doc:`Filling Documents <../gamedata/filling_documents>` 35 | - :doc:`Publication of Game Data <../gamedata/publication>` 36 | - :doc:`Generating Source Code <../gamedata/generating_source_code>` 37 | - :doc:`Working with Source Code (C# 4.0) <../gamedata/working_with_csharp_code_4_0>` 38 | - :doc:`Working with Source Code (C# 7.3) <../gamedata/working_with_csharp_code_7_3>` 39 | - :doc:`Working with Source Code (TypeScript) <../gamedata/working_with_type_script_code>` 40 | - :doc:`Frequently Asked Questions (FAQ) <../faq>` 41 | - :doc:`Glossary <../glossary>` -------------------------------------------------------------------------------- /docs/web/permission_and_roles.rst: -------------------------------------------------------------------------------- 1 | Roles and Permissions 2 | ======== 3 | 4 | The web version of the Charon provides a system of roles and permissions to manage access and control over your game development projects. 5 | Each role is designed to provide specific levels of access and functionality within the platform. 6 | Here are the key roles , along with their respective permissions: 7 | 8 | Viewer Role: 9 | - View Documents: Users with the Viewer role can access and view documents within projects. 10 | - Export Data: Viewers can export data from the platform. 11 | - Access Project Settings: They can access and view project settings. 12 | 13 | Editor Role: 14 | - View Documents: Editors can view documents. 15 | - Edit Documents: Editors have the ability to edit documents within projects. 16 | - Import Data: They can import data into the platform. 17 | - Access Project Settings: Similar to Viewers, Editors can access and view project settings. 18 | 19 | Designer Role: 20 | - Change Document Structure: Designers have the privilege to modify the structure of documents. 21 | - View Documents: Designers can view documents. 22 | - Edit Documents: They can edit documents. 23 | - Import Data: Designers can import data. 24 | - Access Project Settings: They can access and view project settings. 25 | 26 | Administrator Role: 27 | - Make and Restore Backups: Administrators have the authority to create and restore backups of project data. 28 | - Grant or Revoke Permissions: They can grant or revoke permissions for users within the project. 29 | - Change Project Settings: Administrators can modify various project settings to tailor the environment to their needs. 30 | - View Documents: Administrators can view documents. 31 | - Edit Documents: They can edit documents. 32 | - Import Data: Administrators can import data. 33 | 34 | Workspace Administrator and Workspace Owner Role: 35 | - They have the same permissions as Administrators, and they also have the ability to delete and transfer projects. 36 | 37 | See also 38 | -------- 39 | 40 | - :doc:`Overview ` 41 | - `Web-based Application `_ 42 | -------------------------------------------------------------------------------- /docs/web/rest.rst: -------------------------------------------------------------------------------- 1 | REST API 2 | ======== 3 | 4 | The web version of the Charon provides a experimental REST API feature. 5 | 6 | Testing REST API 7 | --------------------- 8 | You can utilize the `Swagger UI `_ to perform test requests. In the *Swagger UI*, click on the *Authorize* button and paste your :doc:`API Key ` for authentication. 9 | 10 | Working with REST API 11 | --------------------- 12 | To make requests, you will need an :doc:`API Key ` obtained from your profile page. Add the `Authorization: `_ ``Basic `` header to all of your HTTP requests. Also is recommeded to provide correct `User-Agent `_ header. 13 | 14 | .. openapi:: ../openapi.yml 15 | :group: 16 | :exclude: 17 | /app/* 18 | /billing/notification/ -------------------------------------------------------------------------------- /scripts/bootstrap/RunCharon.bat: -------------------------------------------------------------------------------- 1 | @echo off 2 | setlocal 3 | 4 | :: Find current directory of the script 5 | 6 | SETLOCAL ENABLEDELAYEDEXPANSION 7 | set DRIVE_LETTER=%~d0 8 | FOR %%Z IN (A B C D E F G H I J K L M N O P Q R S T U V W X Y Z) DO SET DRIVE_LETTER=!DRIVE_LETTER:%%Z=%%Z! 9 | SETLOCAL DISABLEDELAYEDEXPANSION 10 | 11 | set "SCRIPT_DIR=%DRIVE_LETTER%%~p0" 12 | 13 | :: Check if dotnet is installed 14 | :Check_Dotnet 15 | 16 | where dotnet >nul 2>&1 17 | if %ERRORLEVEL% NEQ 0 ( 18 | goto Exit_No_Dotnet_Installed 19 | ) 20 | 21 | :: Get the installed dotnet version 22 | for /f "tokens=*" %%i in ('dotnet --version') do set "DOTNET_VERSION=%%i" 23 | 24 | :: Extract the major version number 25 | for /f "tokens=1 delims=." %%a in ("%DOTNET_VERSION%") do set "MAJOR_VERSION=%%a" 26 | 27 | :: Check if the major version is 8 or later 28 | if %MAJOR_VERSION% LSS 8 ( 29 | goto Old_Dotnet_Installed 30 | ) 31 | 32 | :: Install/Update charon tool 33 | :Install_Update_Charon_Tool 34 | 35 | pushd "%SCRIPT_DIR%" 36 | if NOT EXIST ".config\dotnet-tools.json" ( 37 | dotnet new tool-manifest -o . >nul 38 | ) 39 | dotnet tool list --local | findstr /i /c:"dotnet-charon" >nul 2>&1 40 | if %ERRORLEVEL% EQU 0 ( 41 | dotnet tool update dotnet-charon --local --tool-manifest .config/dotnet-tools.json >nul 42 | ) else ( 43 | dotnet tool install dotnet-charon --local --tool-manifest .config/dotnet-tools.json >nul 44 | 45 | if %ERRORLEVEL% NEQ 0 ( 46 | popd 47 | goto Exit_Failure_Dotnet_Restore_Failed 48 | ) 49 | ) 50 | popd 51 | 52 | :: Run charon tool with specified parameters 53 | :Run_Tool 54 | 55 | pushd "%SCRIPT_DIR%" 56 | dotnet charon %* 57 | set EXITCODE=%ERRORLEVEL% 58 | popd 59 | 60 | if %EXITCODE% NEQ 0 ( 61 | goto Exit_Failure 62 | ) else ( 63 | goto Exit_Success 64 | ) 65 | 66 | goto Exit_Success 67 | 68 | :Exit_Failure_Dotnet_Restore_Failed 69 | set EXITCODE=-2 70 | echo Failed to execute the 'dotnet tool install dotnet-charon' command to retrieve the latest package version from NuGet. Ensure that the 'dotnet' tool is installed and available in the 'PATH'. Check 'https://dotnet.microsoft.com/en-us/download' for the installer. 1>&2 71 | goto Exit_Failure 72 | 73 | :Exit_No_Dotnet_Installed 74 | set EXITCODE=-3 75 | echo .NET SDK is not installed. 1>&2 76 | goto Exit_Failure 77 | 78 | :Old_Dotnet_Installed 79 | set EXITCODE=-4 80 | echo ".NET version %DOTNET_VERSION% is installed, but it is not version 8 or later." 1>&2 81 | goto Exit_Failure 82 | 83 | :Exit_Failure 84 | exit /B %EXITCODE% 85 | 86 | :Exit_Success 87 | exit /B 0 88 | -------------------------------------------------------------------------------- /scripts/bootstrap/RunCharon.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Add typical paths for mono and dotnet to PATH 4 | export PATH=$PATH:/usr/local/bin:/usr/bin:/usr/sbin:/opt/homebrew/bin:/opt/local/bin:/usr/local/share/dotnet:/usr/share/dotnet:/snap/bin 5 | 6 | 7 | # Find the current directory of the script 8 | SCRIPT_DIR=$(cd "`dirname "$0"`" && pwd) 9 | 10 | # Check if dotnet is installed 11 | check_dotnet() { 12 | if ! command -v dotnet &> /dev/null; then 13 | echo ".NET SDK is not installed." >&2 14 | echo "Please install .NET SDK from https://dotnet.microsoft.com/en-us/download" >&2 15 | exit 1 16 | fi 17 | } 18 | 19 | # Get the installed dotnet version 20 | get_dotnet_version() { 21 | DOTNET_VERSION=$(dotnet --version 2>/dev/null) 22 | if [ -z "$DOTNET_VERSION" ]; then 23 | echo "Failed to retrieve .NET version. Ensure 'dotnet' is installed and available in the PATH." >&2 24 | exit 1 25 | fi 26 | MAJOR_VERSION=$(echo "$DOTNET_VERSION" | cut -d. -f1) 27 | } 28 | 29 | # Check if the major version is 8 or later 30 | check_dotnet_version() { 31 | if [ "$MAJOR_VERSION" -lt 8 ]; then 32 | echo ".NET version $DOTNET_VERSION is installed, but it is not version 8 or later." >&2 33 | echo "Please install .NET 8 or later from https://dotnet.microsoft.com/en-us/download" >&2 34 | exit 1 35 | fi 36 | } 37 | 38 | # Install/Update charon tool 39 | install_update_charon_tool() { 40 | pushd "$SCRIPT_DIR" > /dev/null || exit 1 41 | if [ ! -f ".config/dotnet-tools.json" ]; then 42 | dotnet new tool-manifest -o . > /dev/null 2>&1; 43 | fi 44 | if dotnet tool list --local | grep -q 'dotnet-charon'; then 45 | dotnet tool update dotnet-charon --local --tool-manifest .config/dotnet-tools.json > /dev/null 2>&1; 46 | else 47 | if ! dotnet tool install dotnet-charon --local --tool-manifest .config/dotnet-tools.json > /dev/null 2>&1; then 48 | echo "Failed to execute the 'dotnet tool install dotnet-charon' command to retrieve the latest package version from NuGet." >&2 49 | echo "Ensure that the 'dotnet' tool is installed and available in the 'PATH'." >&2 50 | echo "Check https://dotnet.microsoft.com/en-us/download for the installer." >&2 51 | popd > /dev/null || exit 1 52 | exit 1 53 | fi 54 | fi 55 | popd > /dev/null || exit 1 56 | } 57 | 58 | # Run charon tool with specified parameters 59 | run_tool() { 60 | pushd "$SCRIPT_DIR" > /dev/null || exit 1 61 | dotnet charon "$@" 62 | EXITCODE=$? 63 | popd > /dev/null || exit 1 64 | 65 | if [ "$EXITCODE" -ne 0 ]; then 66 | exit "$EXITCODE" 67 | fi 68 | } 69 | 70 | # Main script execution 71 | check_dotnet 72 | get_dotnet_version 73 | check_dotnet_version 74 | install_update_charon_tool 75 | run_tool "$@" 76 | 77 | # Exit successfully 78 | exit 0 79 | -------------------------------------------------------------------------------- /scripts/bootstrap/RunT4.bat: -------------------------------------------------------------------------------- 1 | @echo off 2 | setlocal 3 | 4 | :: Find current directory of the script 5 | 6 | SETLOCAL ENABLEDELAYEDEXPANSION 7 | set DRIVE_LETTER=%~d0 8 | FOR %%Z IN (A B C D E F G H I J K L M N O P Q R S T U V W X Y Z) DO SET DRIVE_LETTER=!DRIVE_LETTER:%%Z=%%Z! 9 | SETLOCAL DISABLEDELAYEDEXPANSION 10 | 11 | set "SCRIPT_DIR=%DRIVE_LETTER%%~p0" 12 | 13 | :: Check if dotnet is installed 14 | :Check_Dotnet 15 | 16 | where dotnet >nul 2>&1 17 | if %ERRORLEVEL% NEQ 0 ( 18 | goto Exit_No_Dotnet_Installed 19 | ) 20 | 21 | :: Get the installed dotnet version 22 | for /f "tokens=*" %%i in ('dotnet --version') do set "DOTNET_VERSION=%%i" 23 | 24 | :: Extract the major version number 25 | for /f "tokens=1 delims=." %%a in ("%DOTNET_VERSION%") do set "MAJOR_VERSION=%%a" 26 | 27 | :: Check if the major version is 8 or later 28 | if %MAJOR_VERSION% LSS 8 ( 29 | goto Old_Dotnet_Installed 30 | ) 31 | 32 | :: Install/Update t4 tool 33 | :Install_Update_T4_Tool 34 | 35 | pushd "%SCRIPT_DIR%" 36 | dotnet tool list --local | findstr /i /c:"dotnet-t4" >nul 2>&1 37 | if NOT EXIST ".config\dotnet-tools.json" ( 38 | dotnet new tool-manifest -o . >nul 39 | ) 40 | if %ERRORLEVEL% EQU 0 ( 41 | dotnet tool update dotnet-t4 --local --tool-manifest .config/dotnet-tools.json >nul 42 | ) else ( 43 | dotnet tool install dotnet-t4 --local --tool-manifest .config/dotnet-tools.json >nul 44 | 45 | if %ERRORLEVEL% NEQ 0 ( 46 | popd 47 | goto Exit_Failure_Dotnet_Restore_Failed 48 | ) 49 | ) 50 | popd 51 | 52 | :: Run charon tool with specified parameters 53 | :Run_Tool 54 | 55 | pushd "%SCRIPT_DIR%" 56 | dotnet t4 %* 57 | set EXITCODE=%ERRORLEVEL% 58 | popd 59 | 60 | if %EXITCODE% NEQ 0 ( 61 | goto Exit_Failure 62 | ) else ( 63 | goto Exit_Success 64 | ) 65 | 66 | goto Exit_Success 67 | 68 | :Exit_Failure_Dotnet_Restore_Failed 69 | set EXITCODE=-2 70 | echo Failed to execute the 'dotnet tool install dotnet-t4' command to retrieve the latest package version from NuGet. Ensure that the 'dotnet' tool is installed and available in the 'PATH'. Check 'https://dotnet.microsoft.com/en-us/download' for the installer. 1>&2 71 | goto Exit_Failure 72 | 73 | :Exit_No_Dotnet_Installed 74 | set EXITCODE=-3 75 | echo .NET SDK is not installed. 1>&2 76 | goto Exit_Failure 77 | 78 | :Old_Dotnet_Installed 79 | set EXITCODE=-4 80 | echo ".NET version %DOTNET_VERSION% is installed, but it is not version 8 or later." 1>&2 81 | goto Exit_Failure 82 | 83 | :Exit_Failure 84 | exit /B %EXITCODE% 85 | 86 | :Exit_Success 87 | exit /B 0 88 | -------------------------------------------------------------------------------- /scripts/bootstrap/RunT4.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Add typical paths for mono and dotnet to PATH 4 | export PATH=$PATH:/usr/local/bin:/usr/bin:/usr/sbin:/opt/homebrew/bin:/opt/local/bin:/usr/local/share/dotnet:/usr/share/dotnet:/snap/bin 5 | 6 | 7 | # Find the current directory of the script 8 | SCRIPT_DIR=$(cd "`dirname "$0"`" && pwd) 9 | 10 | # Check if dotnet is installed 11 | check_dotnet() { 12 | if ! command -v dotnet &> /dev/null; then 13 | echo ".NET SDK is not installed." >&2 14 | echo "Please install .NET SDK from https://dotnet.microsoft.com/en-us/download" >&2 15 | exit 1 16 | fi 17 | } 18 | 19 | # Get the installed dotnet version 20 | get_dotnet_version() { 21 | DOTNET_VERSION=$(dotnet --version 2>/dev/null) 22 | if [ -z "$DOTNET_VERSION" ]; then 23 | echo "Failed to retrieve .NET version. Ensure 'dotnet' is installed and available in the PATH." >&2 24 | exit 1 25 | fi 26 | MAJOR_VERSION=$(echo "$DOTNET_VERSION" | cut -d. -f1) 27 | } 28 | 29 | # Check if the major version is 8 or later 30 | check_dotnet_version() { 31 | if [ "$MAJOR_VERSION" -lt 8 ]; then 32 | echo ".NET version $DOTNET_VERSION is installed, but it is not version 8 or later." >&2 33 | echo "Please install .NET 8 or later from https://dotnet.microsoft.com/en-us/download" >&2 34 | exit 1 35 | fi 36 | } 37 | 38 | # Install/Update t4 tool 39 | install_update_t4_tool() { 40 | pushd "$SCRIPT_DIR" > /dev/null || exit 1 41 | if [ ! -f ".config/dotnet-tools.json" ]; then 42 | dotnet new tool-manifest -o . > /dev/null 2>&1; 43 | fi 44 | if dotnet tool list --local | grep -q 'dotnet-t4'; then 45 | dotnet tool update dotnet-t4 --local --tool-manifest .config/dotnet-tools.json > /dev/null 2>&1; 46 | else 47 | if ! dotnet tool install dotnet-t4 --local --tool-manifest .config/dotnet-tools.json > /dev/null 2>&1; then 48 | echo "Failed to execute the 'dotnet tool install dotnet-t4' command to retrieve the latest package version from NuGet." >&2 49 | echo "Ensure that the 'dotnet' tool is installed and available in the 'PATH'." >&2 50 | echo "Check https://dotnet.microsoft.com/en-us/download for the installer." >&2 51 | popd > /dev/null || exit 1 52 | exit 1 53 | fi 54 | fi 55 | popd > /dev/null || exit 1 56 | } 57 | 58 | # Run t4 tool with specified parameters 59 | run_tool() { 60 | pushd "$SCRIPT_DIR" > /dev/null || exit 1 61 | dotnet t4 "$@" 62 | EXITCODE=$? 63 | popd > /dev/null || exit 1 64 | 65 | if [ "$EXITCODE" -ne 0 ]; then 66 | exit "$EXITCODE" 67 | fi 68 | } 69 | 70 | # Main script execution 71 | check_dotnet 72 | get_dotnet_version 73 | check_dotnet_version 74 | install_update_t4_tool 75 | run_tool "$@" 76 | 77 | # Exit successfully 78 | exit 0 79 | --------------------------------------------------------------------------------