639 lines
13 KiB
Markdown
639 lines
13 KiB
Markdown
# JSON format
|
|
This document provides an overview of the JSON serializer format. For an overview of how to use the JSON serializer API, [see the JSON addon documentation](https://www.flecs.dev/flecs/group__c__addons__json.html).
|
|
|
|
## Value kinds
|
|
This section describes value kinds that are used by the JSON serializers.
|
|
|
|
### Name
|
|
A name field returns the name of an entity as returned by `ecs_get_name` or `flecs::entity::name`.
|
|
|
|
**Example**:
|
|
```json
|
|
"Earth"
|
|
```
|
|
|
|
### Path
|
|
A path field returns the path identifier of an entity as returned by `ecs_get_fullpath` or `flecs::entity::path`. The path contains the entity's name and the names of its parent and grandparents separated by a dot (`.`).
|
|
|
|
**Example**:
|
|
```json
|
|
"SolarSystem.Sun.Earth"
|
|
```
|
|
|
|
### Label
|
|
A label field returns the doc name of the entity as returned by `ecs_doc_get_name` or `flecs::entity::doc_name`. The doc name is a user-friendly name for the entity that does not need to be unique and may contain any character.
|
|
|
|
Serializing labels requires the [doc](https://www.flecs.dev/flecs/group__c__addons__doc.html) addon.
|
|
|
|
**Example**:
|
|
```json
|
|
"The Earth"
|
|
```
|
|
|
|
### Id
|
|
An id field returns a component id or pair. It is formatted as an array of at least one and at most three elements where the elements have the following meaning:
|
|
|
|
- Component _or_ First element of pair
|
|
- Second element of pair
|
|
- Type flag
|
|
|
|
Each element is formatted as a [Path](#path).
|
|
|
|
**Example**:
|
|
```json
|
|
["transform.Position"]
|
|
["Likes", "Apples"]
|
|
["Movement", 0, "SWITCH"]
|
|
```
|
|
|
|
### Id**
|
|
Same as [Id](#id) but with [Label](#label)'s instead of paths.
|
|
|
|
**Example**:
|
|
```json
|
|
["Entity position"]
|
|
["Located in", "San Francisco"]
|
|
```
|
|
|
|
### Value
|
|
A JSON object or scalar representing the value of a component. Component values can only be serialized if the component is described in the reflection framework (see the [meta addon](https://www.flecs.dev/flecs/group__c__addons__meta.html)).
|
|
|
|
When a component has no value (e.g. a tag) or is not described by the reflection framework, `0` will be used as placeholder.
|
|
|
|
**Example**:
|
|
```json
|
|
{"x": 10, "y": 20}
|
|
```
|
|
|
|
### Type**
|
|
A JSON object that represents the structure of a component type.
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"type_info": [{
|
|
"x": ["float"],
|
|
"y": ["float"]
|
|
}, 0, 0]
|
|
}
|
|
```
|
|
|
|
### Entity
|
|
The entity kind is an object that contains metadata and data of a single serialized entity, and is returned by the [Entity serializer](#entity-serializer).
|
|
|
|
The following sections describe the fields that an object of the entity kind may contain:
|
|
|
|
#### "path
|
|
The entity path.
|
|
|
|
Type: [Path](#path), optional
|
|
|
|
#### "label
|
|
The entity doc name.
|
|
|
|
Type: [Label](#label), optional
|
|
|
|
#### "brief
|
|
Brief description (as returned by `ecs_doc_get_brief`).
|
|
|
|
Type: string, optional
|
|
|
|
#### "link
|
|
Link to URL (as returned by `ecs_doc_get_link`).
|
|
|
|
Type: string, optional
|
|
|
|
#### "is_a
|
|
Base entities.
|
|
|
|
Type: Array([Entity](#entity)), optional
|
|
|
|
#### "ids
|
|
Component ids.
|
|
|
|
Type: Array([Id](#id))
|
|
|
|
#### "id_labels
|
|
Component labels.
|
|
|
|
Type: Array([Id label](#id-label)), optional
|
|
|
|
#### "hidden
|
|
Array indicating whether a component is hidden. Only applies to components of base entities (in the ["is_a"](is_a) array).
|
|
|
|
A base component is hidden when it is overridden by an entity higher in the inheritance hierarchy.
|
|
|
|
Type: Array(bool), optional
|
|
|
|
#### "values
|
|
Component values.
|
|
|
|
Type: Array([Value](#value)), optional
|
|
|
|
#### "type_info
|
|
Array with objects that describe the component types of the terms.
|
|
|
|
Type: Array([Type info](#type-info)), optional
|
|
|
|
#### Example
|
|
Default serializer options:
|
|
```json
|
|
{
|
|
"path":"Sun.Earth",
|
|
"ids":[
|
|
["Position"],
|
|
["flecs.core.ChildOf", "Sun"],
|
|
["flecs.core.Identifier", "flecs.core.Name"]
|
|
]
|
|
}
|
|
```
|
|
|
|
This example shows an entity with a base (an `IsA` relationship) with default serializer options:
|
|
```json
|
|
{
|
|
"path":"Sun.Earth",
|
|
"is_a": [{
|
|
"path":"planets.RockyPlanet",
|
|
"ids": [
|
|
["planets.HasRocks"]
|
|
]
|
|
}],
|
|
"ids":[
|
|
["Position"],
|
|
["flecs.core.ChildOf", "Sun"],
|
|
["flecs.core.Identifier", "flecs.core.Name"]
|
|
]
|
|
}
|
|
```
|
|
|
|
This example shows an entity with a base with all serializer options enabled:
|
|
```json
|
|
{
|
|
"path":"Sun.Earth",
|
|
"label": "The Earth",
|
|
"brief": "The planet you call home",
|
|
"link": "www.earth.com",
|
|
"is_a": [{
|
|
"path":"planets.RockyPlanet",
|
|
"label":"A rocky planet",
|
|
"ids": [
|
|
["Position"],
|
|
["planets.HasRocks"]
|
|
],
|
|
"id_labels": [
|
|
["Position"],
|
|
["HasRocks"]
|
|
],
|
|
"values":[0, 0],
|
|
"hidden":[true, false]
|
|
}],
|
|
"ids":[
|
|
["Position"],
|
|
["flecs.core.ChildOf", "Sun"],
|
|
["flecs.core.Identifier", "flecs.core.Name"]
|
|
],
|
|
"ids_labels":[
|
|
["Position"],
|
|
["ChildOf", "Sun"],
|
|
["Identifier", "Name"]
|
|
],
|
|
"values":[
|
|
{"x": 10, "y": 20},
|
|
0, 0
|
|
],
|
|
"type_info": [{
|
|
"x": ["float"],
|
|
"y": ["float"]
|
|
}, 0, 0]
|
|
}
|
|
```
|
|
|
|
### Result
|
|
The result kind is an object that contains the metadata and data of a single result returned by an iterator (see [Iterator](#iterator)).
|
|
|
|
The following sections describe the fields that an object of the entity kind may contain:
|
|
|
|
#### parent
|
|
Parent of the entity in current result.
|
|
|
|
Type: Array([Path](#path)), optional
|
|
|
|
#### entities
|
|
Array with paths of the returned entities.
|
|
|
|
Type: Array([Name](#name)), optional
|
|
|
|
#### entity_labels
|
|
Same as [entities](#entities), but with [Label](#label)'s instead of paths.
|
|
|
|
Type: Array([Label](#label)), optional
|
|
|
|
#### entity_ids
|
|
Same as [entities](#entities), but with numerical ids instead of paths.
|
|
|
|
Type: Array(Number), optional
|
|
|
|
#### sources
|
|
Array with paths of sources for each term. A subject indicates the actual entity on which a component is stored. If this is the matched entity (default) the array will contain a `0` element.
|
|
|
|
Type: Array([Path](#path)), optional
|
|
|
|
#### variables
|
|
Array with variable values for current result (see [query variables](Queries.md#variables)).
|
|
|
|
Type: Array([Path](#path)), optional
|
|
|
|
#### variable_labels
|
|
Same as [variables](#variables), but with [Label](#label)'s instead of paths.
|
|
|
|
Type: Array([Label](#label)), optional
|
|
|
|
#### variable_ids
|
|
Same as [variables](#variables), but with numerical ids instead of paths.
|
|
|
|
Type: Array(Number), optional
|
|
|
|
#### ids
|
|
Array with component ids. This list is more specific than the ids array provided by the top-level iterator object. The arrays can be different in the case of terms with an `Or` operator, or terms with wildcard ids.
|
|
|
|
Type: Array(string), optional
|
|
|
|
#### is_set
|
|
Array with booleans that can be used to determine whether terms with the `Optional` operator are set.
|
|
|
|
Type: Array(bool), optional
|
|
|
|
#### values
|
|
Array with component values. The array contains an element for each term. If a component has no value, or no value could be serialized for the component a `[]` element is added.
|
|
|
|
Each element in the array can be either an array with component values when the component is from the matched entity, or a single component value when the component is from another entity (like a parent, prefab, singleton).
|
|
|
|
Type: Array(Array([Value](#value))), optional
|
|
|
|
### Iterator
|
|
The iterator kind is an object that contains metadata and data of all the entities yielded by an iterator.
|
|
|
|
#### "ids
|
|
Array with ids for each term.
|
|
|
|
Type: Array(string), optional
|
|
|
|
#### "variables
|
|
Array with variable names (see [query variables](https://www.flecs.dev/flecs/md_docs_Queries.html/#variables)).
|
|
|
|
Type: Array(string), optional
|
|
|
|
#### "results
|
|
Array with elements for each returned result.
|
|
|
|
Type: Array([Result](#result))
|
|
|
|
#### "eval_duration
|
|
Time it took to serialize the iterator.
|
|
|
|
Type: Number
|
|
|
|
#### "type_info
|
|
Array with objects that describe the component types of the terms.
|
|
|
|
Type: Array([Type info](#type-info)), optional
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{
|
|
"ids": ["Position", "Jedi"],
|
|
"results": [{
|
|
"entities": ["Luke", "Yoda"],
|
|
"values": [
|
|
[{ "x": 10, "y": 20 },
|
|
{ "x": 20, "y": 30 }],
|
|
0
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
## Entity serializer
|
|
The entity serializer returns a JSON string of the [Entity](#entity) type. This format is returned by `ecs_entity_to_json` and `flecs::entity::to_json`.
|
|
|
|
### Serializer options
|
|
The following options (found in `ecs_entity_to_json_desc_t`) customize the output of the entity serializer:
|
|
|
|
#### serialize_path
|
|
Serialize the ["path"](#path-1) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
```json
|
|
{"path": "SolarSystem.Sun.Earth"}
|
|
```
|
|
|
|
#### serialize_label
|
|
Serialize the ["label"](#label-1) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{"label": "Rocky planet"}
|
|
```
|
|
|
|
#### serialize_brief
|
|
Serialize the ["brief"](#brief) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{"brief": "A rocky planet"}
|
|
```
|
|
|
|
#### serialize_link
|
|
Serialize the ["link"](#link) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{"brief": "www.rocky-planet.com"}
|
|
```
|
|
|
|
#### serialize_id_labels
|
|
Serializes the ["id_labels"](#id_labels) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{"id_labels": [["A Rocky Planet"], ["Has surface water"]]}
|
|
```
|
|
|
|
#### serialize_base
|
|
Serializes the ["is_a"](#is_a) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
```json
|
|
{"is_a": [{
|
|
"path":"planets.RockyPlanet",
|
|
"ids": [
|
|
["planets.HasRocks"]
|
|
]
|
|
}]}
|
|
```
|
|
|
|
#### serialize_private
|
|
Serialize private components. Private components are regular components with the `EcsPrivate` (or `flecs::Private`) tag. When `serialize_private` is false, private components will be hidden from all arrays.
|
|
|
|
**Example**:
|
|
```json
|
|
{"ids": ["Position", "PrivateComponent"]}
|
|
```
|
|
|
|
**Default**: `false`
|
|
|
|
#### serialize_hidden
|
|
Serializes the ["hidden"](#hidden) member.
|
|
|
|
**Example**:
|
|
```json
|
|
{"hidden":[true, false]}
|
|
```
|
|
|
|
Full example:
|
|
```json
|
|
{
|
|
"path":"Sun.Earth",
|
|
"is_a": [{
|
|
"path":"planets.RockyPlanet",
|
|
"ids": [
|
|
["Position"],
|
|
["planets.HasRocks"]
|
|
],
|
|
"hidden":[true, false]
|
|
}],
|
|
"ids":[
|
|
["Position"],
|
|
["flecs.core.ChildOf", "Sun"],
|
|
["flecs.core.Identifier", "flecs.core.Name"]
|
|
]
|
|
}
|
|
```
|
|
Note that `hidden[0]` is `true` in this example, because the `Position` component from `planets.RockyPlanet` is overridden by the entity.
|
|
|
|
**Default**: `false`
|
|
|
|
#### serialize_values
|
|
Serializes the ["values"](#values) member.
|
|
|
|
**Example**:
|
|
```json
|
|
{"values":[{"x":10, "y": 20}, 0]}
|
|
```
|
|
|
|
**Default**: `false`
|
|
|
|
#### serialize_type_info
|
|
Serialize the ["type_info"](#type_info) member.
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"type_info": [{
|
|
"x": ["float"],
|
|
"y": ["float"]
|
|
}, 0, 0]
|
|
}
|
|
```
|
|
|
|
## Iterator serializer
|
|
The entity serializer returns a JSON string of the [Iterator](#iterator) type. This format is returned by `ecs_iter_to_json`.
|
|
|
|
### Serializer options
|
|
|
|
#### serialize_term_ids
|
|
Serialize the top level ["ids"](#term_ids) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position, Jedi`
|
|
```json
|
|
{
|
|
"ids": ["Position", "Jedi"],
|
|
"results": [ ]
|
|
}
|
|
```
|
|
|
|
#### serialize_ids
|
|
Serialize the result specific ["ids"](#ids-1) member.
|
|
|
|
If the iterated query does not contain variable ids (either an `Or` term or a term with a wildcard id) the result specific `ids` member will exactly match the top-level `ids` member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position, (Likes, *)`
|
|
```json
|
|
{
|
|
"ids": ["Position", "(Likes,*)"],
|
|
"results": [{
|
|
"ids": ["Position", "(Likes,Apples)"]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_sources
|
|
Serialize the ["sources"](#sources) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position, Position(parent)`
|
|
```json
|
|
{
|
|
"ids": ["Position", "Position"],
|
|
"results": [{
|
|
"entities": ["Parent.A", "Parent.B"],
|
|
"sources": [0, "Parent"]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_variables
|
|
Serialize the ["variables"](#variables) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position, (Likes, _Food)`
|
|
```json
|
|
{
|
|
"variables": ["Food"],
|
|
"results": [{
|
|
"ids": ["Position", "(Likes,Apples)"],
|
|
"variables": ["Apples"],
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_is_set
|
|
Serialize the ["is_set"](#is_set) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position, ?Velocity`
|
|
```json
|
|
{
|
|
"ids": ["Position", "Velocity"],
|
|
"results": [{
|
|
"is_set": [true, false]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_values
|
|
Serialize the ["values"](#values) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
|
|
Example result for query `Position`
|
|
```json
|
|
{
|
|
"ids": ["Position"],
|
|
"results": [{
|
|
"values": [
|
|
[{
|
|
"x": 10,
|
|
"y": 20
|
|
}]
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_entities
|
|
Serialize the ["entities"](#entities) member.
|
|
|
|
**Default**: `true`
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"results": [{
|
|
"entities": ["MyEntity"]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_entity_labels
|
|
Serialize the ["entity_labels"](#entity_labels) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"results": [{
|
|
"entities": ["Parent.MyEntity"],
|
|
"entity_labels": ["My entity"]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### serialize_variable_labels
|
|
Serialize the ["variable_labels"](#variable_labels) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"results": [{
|
|
"variables": ["GrannySmith"],
|
|
"variable_labels": ["Granny smith"]
|
|
}]
|
|
}
|
|
```
|
|
|
|
#### measure_eval_duration
|
|
Serialize the ["eval_duration"](#eval_duration) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"eval_duration": 0.001
|
|
}
|
|
```
|
|
|
|
#### serialize_type_info
|
|
Serialize the ["type_info"](#type_info_1) member.
|
|
|
|
**Default**: `false`
|
|
|
|
**Example**:
|
|
```json
|
|
{
|
|
"ids": ["Position", "Jedi"],
|
|
"type_info": [{
|
|
"x": ["float"],
|
|
"y": ["float"]
|
|
}, 0],
|
|
"results": [{
|
|
}]
|
|
}
|
|
```
|