AGS 4 Draft: Game Data and Entities - adventuregamestudio/ags GitHub Wiki

-- Common Definitions

Game Data: what defines a game. Asset: a distinct piece of Game Data. Game Source: an original game assets provided by user. Game Package: a final game form that can be run by the Engine. This is how game is supposed to be distributed. ** NB **: Game Source and Game Package may be represented by same format or different ones. Engine: a program that loads and executes Game Data. Runtime Data: a game represented in the engine's memory. Game Logic: rules that determine how the engine uses game data and runs the game. Build Tools: non-visual (no GUI) programs that convert Game Project into the runnable Game Data. Game Building: a process of converting Game Source into Game Data. This involves using Build Tools. IDE: a visual program, with graphical user interface, that helps user work with the Game Source, run Game Building, and other operations.

-- Game and Data

Game is built of Assets. Assets are: Entity definitions, Scripts and [Media] Resources. Entity is a dynamically created object that acts in game. Entities are described with Properties. Entities can be created, deleted, have their state changed, execute commands, provide feedback. Scripts are programs that are run by the engine as a custom part of Game Logic. Engine may provide default game program as an optional separate component. So do plugins. [Media] Resources provide means of representing the game and its entities, like visuals, audio, text, or else.

-- Entities and their behavior

Entities are defined by their properties. Properties are universal and consistent, in the sense that a property may be addressed at design time or runtime, changed by the engine's built-in behavior, by loading and applying a data file, by script, by plugin.

Entity has a game-wide unique ID that allows to reference it.

All entities may be created, modified, saved, loaded or deleted anytime. Loading entities from game data should be no different from loading them from a game save, or instantiating them in script.

The guideline for properties and behaviors is such that if the engine can implement certain entity behavior, then script or plugin could implement same behavior by using only exposed entity properties. This guarantees that there's no hidden mechanism in the game logic, and user may recreate and adjust any behavior. Default game logic may be implemented in the engine, but it may be likewise be implemented by user in a script or plugin. The game system should be organized so that it might be possible to have game logic purely in script, with engine only providing low-level functionality (rendering, IO, etc).

-- Entity relations

FIXME: this whole section must be reviewed and rewritten, as the subject is not explained very well.

Two basic entity relations are ownership and parentship.

Ownership affects the entity lifetime and serialization. Subjects are destroyed if owner was destroyed. By default subjects are also serialized when owner is serialized. Entities may have any number of subjects (owned entities) and one owner (if this entity is a subject of another).

Parentship defines how the behavior of one entity (parent) overrides others (children). The affected behaviors may be expanded in advanced entity subtypes. The common example is transform property: for entities that define "position" in space, children's position will be applied relatively to their parent's. This means that if parent moves then all children move along, and if child has a motion of its own then it produces a relative motion around parent. Entities may have any number of children and one parent (if this entity is a child of another).

TODO: perhaps not the best choice of terms, may it be confusing? perhaps better do "parent" (instead of "owner") and something else like "attaching" (instead of "parent"); also see a practical example below which maybe give a hint.

Owner and parent of an entity may be assigned and changed anytime. Entity's owner is the initial parent also. In a common situation owner and parent match, but user may assign different parent, to pursue a special effect. The rule is however that an entity's parent must be either entity's owner or a child of its owner. Therefore a subject entity will always has its owner as a super-parent (directly or indirectly). This rule helps avoiding situations when an owner and subject end up in separate branches of parental relationship and destroying one entity would result in deletion of an entity in parallel hierarchy.

If the entity's parent is deleted and that parent was not the owner, entity just moves one level up along the parental hierarchy.

EXAMPLES:

You may have global and local room characters. Global one is owned by the Game entity and local is owned by the Room entity. When room is loaded global character is made its child to be able to use relative coordinates consistently with everything inside. When room is unloaded, local character is unloaded too, but global one stays and moves up in entity hierarchy to whatever parented this room prior to its disposal.
You may make character a child of a moving platform and it will move along with that platform, and also retain ability to walk around upon that platform. Deleting that platform should not delete the character, it will stay withing the room. Saving a platform as a scene file, or duplicating it should also not use the parented character, as logically it does not belong to platform and its contents (if it had any).

-- Scenes

The Scene is an abstract container, which begins with the root entity which owns and parents all others (directly or indirectly). That may be any kind of entity subtype. All the subjects of this root become part of the scene. It should be possible to create a new scene by extracting or cloning any children from this dependency tree and making topmost entity a new root.

For example, in default implementation there may be a global root Scene called Game. Separate dynamically loaded and unloaded sub-Scenes could be called Rooms. Changing rooms work like unloading a sub-Scene of Game and loading another on its place.

-- Default entity class hierarchy (DRAFT / EXAMPLE)

Entity: foundation of anything else has ID can be a part of a Scene, have parent and children

TODO: how to support events and attach scripts to things?

Thing (or Thing2D), inherits Entity entity in 2D space has transform (position, scale, rotation)
GraphicItem (SpriteItem, etc), inherits Thing has a sprite (can be drawn upon too) has all necessary advanced graphical properties (render layer reference, shader etc)
InteractiveItem (term?), inherits GraphicItem has interaction mask/shape, which helps to determine when the entity is being clicked on

TODO: how to support graphic z-layers? TODO: how to support individual render resolutions? TODO: how to support animations? E.g. Animation/Tween entity similar to AudioPlayback that is given a reference to GraphicItem it animates?

RoomObject, inherits InteractiveItem has 2D collider, supports interacting with other RoomObjects and walkable areas
Character, inherits RoomObject support advanced behavior: Walking, Speaking, etc
Area, inherits Thing has shape
GUI, inherits InteractiveItem
AudioPlayback, inherits Entity
AudioEmitter, inherits Thing defines position of an AudioPlayback in 2D space
Inventory, inherits Entity has a list of stored items, may be attached to anything else to play its inventory. e.g. attached to character as a standard player's inventory, or attached to an object as a chest contents.

and so on