Nebula IDL

The Nebula Intermediate Definition Language (NIDL) can be used to generate C++ code for Properties.

NIDL uses JSON but also supports comments using //.

Generated headers

When generating code from NIDL files, the files are placed in the fips-build/{PROJECT}/{FIPS-CONFIG}/nidl directory. In C++ code, you can include them as if they were placed in the same directory as the .nidl file.

Example:
NIDL file: nebula-demo/code/properties/movement.nidl
C++ include:

#include "properties/movement.h"

NIDL files

1. Namespace
2. Includes
3. Enumerated types
4. Properties

Namespace

"namespace": "GraphicsFeature"

Denotes the namespace for this NIDL file.

Generated types will use this namespace.

Includes

"includes": [
    "math/mat4.h"
    "math/vec4.h"
]

Includes any header specified within the generated files.

Enumerated types

"enums": {
    "GraphicsSettings": {
        "LOW": 0
        "MEDIUM": 1
        "HIGH": 2
    }
}

Declares enumerated types. These can be used as types within properties.

Bug

When used as types in properties, the namespace has to be prepended: "Namespace::EnumType".

Properties

"properties": {
    "Health": "float", // just a regular type
    "Stats": { // struct
        "Strength": "float",
        "IQ": "int",
        "isLarge": {
            "_type_": "bool",
            "_default_": false
        }
    },
    "Target": { // detailed type, not aggregate/struct
        "_type_": "Game::Entity",
        "_default_": -1,
        "_desc_": "Target entity to attack."
    },
    "Movable": "_flag_" // a flag type, will not allocate memory per instance and cannot have a value.
}

Layout

• typedef property

  NAME: Type

• POD struct property:

  NAME: {
      fieldName: Type,
      fieldName: Type,
  }

Type can either be:

• A string or object that declares the type or struct
• A object that contains either:
  • Special fields
    • "_type_": A string or object that declares the type or struct
    • "_default_": A default value
    • "_desc_": A string comment that describes the property
  • or multiple Types, denoting a struct type.

Properties are compiled into C++ structs that can be serialized and deserialized easily. Properties can be added to categories and used to store entities states.

Built in scalar-types are:

• 8 bit: byte, bool
• 16 bit: short, ushort
• 32 bit: int, uint, float
• 64 bit: int64, uint64, double

Built in non-scalar types are:

• vec2 - 2D vector of 32-bit floats.
• vec3 - 3D vector of 32-bit floats*.
  • * Uses 4x32 bits of memory because of SIMD reasons, only 3 components are usable however).
• vec4 - 4D vector of 32-bit floats.
• vector - 4D vector of 32-bit floats*.
  • w value (4th) is always 0. Useful for normals and directional vectors.
• point - 4D vector of 32-bit floats.
  • w value (4th) is always 1. Denotes points in 3d space.
• mat4 - 4x4 matrix of 32-bit floats.
• quat - A quaternion with 32-bit floats.
• resource - A path to a resource.

Additional types are:

• _flag_ - Create a flag type property that will not allocate memory per instance and cannot have a value. This is useful for categorizing entities, for example Static vs Dynamic entities.
• Enumerated type - Any enumerated type defined in a NIDL file can be used as type.
• C++ type
  • Any included C++ headers types can be used as type. Note that C++ type must be trivially destructible and trivially copyable.
  • The type serializers must be manually created. Check the generated NIDL headers and source files for examples (fips-build/{PROJECT}/{FIPS-CONFIG}/nidl).
  • It is required that the type includes its namespace.

The _default_ value can be specified as:

type	value
Integers	10
Floats	3.0
vec2	[1.0, 0.2]
vec4	[1.3, 20.0, 3.12, 4.0]
vector	[1.0, 2.0, 3.0]
point	[1.0, 2.0, 3.0]
quat	[0.0, 0.0, 0.0, 1.0]
mat4	[1,0,0,0,0,1,...] (16 floats)
resource	"mdl:system/placeholder.n3"
Enum Type	Integer or String

The default values for different types (usually zero or identity) can be found in {NEBULA-ROOT}/fips-files/generators/IDLC/idltypes.py.