GameObject Configuration

The configuration for game objects is possibly one of the most important configurations you’ll be using. To keep gameobjects organised i would recommend writing configurations for single game objects into separate files and using the include constructor to load all of them in a single loadable config. After this section you should be able to move a little red square around the screen.

Hint

included files can make use of the same reference file used for the loading of the file they are included in.

objects:
  loader: GameObjectLoader
  config: config/gameobjects.yml
  registry: ObjectRegistry
  loader_args:
    useref: config/ref.yml
content of gameobjects.yml
simple_gameobject: !include gameobjects/simple_gameobject.yml

For the sake of this tutorial we will be constructing a simple gameobject using data already loaded before in Script Configuration and Spritesheet Configuration

scene: default
prefab: false
components:
  - type: TransformComponent2D
    args:
      x: 0
      y: 0
  - type: SpriteComponent
    args:
      asset: red
      layer: 1
  - type: ScriptComponent
    refname: move_script
    args:
      scriptname: move_script
      args:
        step: 32

Despite this configution being fairly short, a lot of things are still happening. First off is the scene key, it tells the program where a game object will be spawned into. The key (nor value) is required and will default to the “default” scene. Objects in different scenes will not be able to interract with eachother.

A second value in the above configuration is prefab, although it is not defined in any configuration file, when using the GameObjectLoader instead of trying to load a gameobject into the game world it’s definition will be stored in the PrefabRegistry for easier access to scripts (see also pg_engine.core.bases.lib_abstract.TGame.spawn()).

the last part of defining a game object is it’s components. PG_Engine is based on an Entity Component System (ECS for short), therefore each component is responsible for one task on the gameobject, like tracking it’s position, holding on to rendering data, etc. components is a list of mappings with two required keys (each) to be considered valid.

components:
  - type: TransformComponent2D
    args:
      x: 20
      y: 20
  - type: SpriteComponent
    args:
      asset: red
      layer: 1
  - type: ScriptComponent
    refname: move_script
    args:
      scriptname: move_script
      args:
        step: 32

The first requirement is a type, like TransformComponent2D, it is a class found in the ClassRegistry (more on creating custom components in Components). The second requirement is the arguments (args) passed to the class’s constructor, they serve as initial values for the component as soon as the game starts. Arguments may be left empty (but not omitted) if the class contains no arguments or they have defaults built into the class (like angle in this case).

Note

Using the concrete implementation of GameObject a transform component may be omitted and one will be constructed on the fly as soon as it is requested. from the one defined in Game Instance Configuration.

!classinit
  type: GameObjectBuilder
  args:
    builder_class: !classget GameObject
    builder_kw:
      transform_class: !classget TransformComponent2D

Components can contain a third optional key refname. By default a component gets registered into a gameobject by it’s classname, however it is not rare for a gameobject to contain multiple scripts (eg. one to handle movement, one to handle health, …) which would then cause name collisions when trying to register multiple components of the same type. For situations like those refname can be used to grant the component a custom name to access the component as instead of it’s classname.

 1components:
 2  - type: TransformComponent2D
 3    args:
 4      x: 20
 5      y: 20
 6  - type: SpriteComponent
 7    args:
 8      asset: red
 9      layer: 1
10  - type: ScriptComponent
11    refname: move_script
12    args:
13      scriptname: move_script
14      args:
15        step: 32

Note

Script components do take a slightly more complex argument structure as each script itself can additionally define one or more arguments to be set as default values. The outer args (line 12) take the name of an exported/imported script from Script Configuration and keyword arguments (inner args, line 14) passed to the script’s __init__.

This component’s refname and scriptname can have different values.