# Core Concepts ## Game Objects & Game Object Properties Machinations Up connects **Game Object Properties** to values in **Machinations Diagrams**. A **Game Object** can be an Actor (such as the Player or an NPC), an Artifact or a Location. A **Game Object** has **Properties**. In Machinations, we are interested in quantifiable properties that are changing throughout the game design. *Good to know: in the Game Design world you may be familiar with* **Game Object Properties** *as* **attributes** *of* **compound entities** *. This is how they are described in the “Machinations bible”, the book “Game Mechanics – Advanced Game Design”. In* **Up** *, all Game Objects are seen as compound entities, and they all have at least one* **Game Object Property** *.* ## Game & Game Object State *The use of this feature is optional.* Even the simplest game has at least two states: Running or Waiting/Lost. More complex games, however, have dozens of states. For example, a strategy game such as Civilization 5 goes through mechanics & UI changes based on what area the Player focuses on. The game state changes from the Map, to the City Overview, the Research Tree, the Policies Page. Each of these has many sub-states, such as Combat Resolution in the Map or Buying Tiles in the City Overview. Designing a complex game needs **both** the holistic approach as well as an in-detail exploration. **Machinations Up** allows this by having Game & Game Object State awareness at its design core. And while Game State may have dozens of states & sub-states **, individual Game Objects** may **each** several other states, completely independent from each other and the game itself. Taking Civilization 5 as an example again, a Warrior may be Traveling, Fighting, Healing. Because these states can be understood by Machinations Up, you are allowed, as a designer, to approach the individual economy of each of your **Game Objects** per state, and even per **Game State**. See below, where we explain how the class StatesAssociation allows this. ## The 6 Main Classes Six classes serve as the cornerstone of Up’s functionality. Here’s a one-liner about each, followed by a more in-depth discussion. **MachinationsGameLayer** – main entry point, handles communication between your game and the Machinations back-end. **MachinationsGameObject** & its subclass **MachinationsGameAwareObject** (*optional*) – are the way you **connect your Game Objects** to Machinations. **MachinationsElement** – wraps a value from the Diagram and oversees the way it changes. Each *MachinationsElement* is eventually bound to a **Game Object Property**. **MachinationsElementBinder** – binds a certain **Game Object Property** to the appropriate *MachinationsElement* based on **Game** and **Game Object**\*\* State\*\*. **StatesAssociation** (*optional*) – represents a combination of **Game** and **Game Object States**. Any combination of any number of states is allowed. **MachinationsGameObjectManifest** – its main use is to define the **Game Object Property Names** that a **Game Object** should get from Machinations. ## In-depth with the 6 main classes **MachinationsGameLayer** – this is the entry point and main orchestrator of all things Machinations UP. This **singleton** class uses [Socket.io](http://socket.io/) to communicate with the Machinations back-end. In Unity, it can be attached to your game via a Prefab we provide, but you can include it in other ways, depending on your project's workflow. **MachinationsGameObject** & its subclass **MachinationsGameAwareObject** – A Game Object (such as the Player or an Enemy) may have multiple **Properties**. These classes allow you to conceptually bundle everything about a **Game Object** together in the same place. They bundle more *MachinationsElementBinder* together, initializing them and dispatching Game State Change notifications to them. See more when we discuss the *StatesAssociation* class below. These classes also host the Game Object’s **Manifest.** **MachinationsElement** – contains: * –Base value: the value retrieved from the Machinations diagram. * –Current value: can only be modified using methods in this Class, such as: * –Reset * –ChangeValueBy * –ChangeValueTo * –Min & Max values. Because the Current value is gated behind accessor functions, MachinationsElement has a tight control over how the value changes. This facilitates keeping the value in a certain range and, in the near future, tracking values using **Machinations Analytics**. **MachinationsElementBinder** – holds at least one **MachinationElement** per **Game Object Property**. However, it also allows **Game Object Properties** to be retrieved from **different Diagrams** based on **Game** and **Game Object**\*\* State\*\*(via the class *StatesAssociation*). This is done using a Dictionary that maps a separate**MachinationsElement** to a unique *StatesAssociation*. You might ask: *“Why isn’t a MachinationsElement bound directly to a Game Object Property”*. That is, indeed, the simplest use case. However, in some games a Game Object Property may change its design based on game state, for example the **speed** of the **player** may change based on environment, and, in more complex/comprehensive game designs, **different Diagrams (designs)** may apply to **different environments**. **MachinationsGameObjectManifest** – it is a declaration of how a **Game Object** interacts with the Machinations back-end. What Game Object Property Names are to be mapped, what Events are to be emitted about a Game Object and so on. It also has methods that the *MachinationsGameLayer* uses in order to build requests for the Machinations back-end. **StatesAssociation** – Bundles together any number of **Game States** (including zero) and any number of **Game Object States** (including zero) under a given Title. It is used by *MachinationsElementBinder* to give the designer the ability of associating a certain **Game Object Property** with a certain **Game/Game Object State** combination. By allowing any number & combination of **Game & Game Object States**, this class allows great flexibility in abstracting game design choices while in the same time being able to carry these choices over to the game. You should only care about this if you intend to use *MachinationGameAwareObject*. ## Interfaces **IGameLifecycleProvider** (optional) – is used by Machinations to query your game engine. Your **game engine SHOULD implement** this **IF** you want to use Game-Aware objects and Game/Game Object States. We provide the class **SampleGameEngine** that implements this interface. We also provide **SampleSceneStartupHandler** to demonstrate how to notify the *MachinationsGameLayer* about your engine. **IGameLifecycleSubscriber** – *MachinationsGameAwareObject* **and** *MachinationsGameLayer* implement this. Your game logic/engine should notify \_MachinationsGameAwareObject\_sof **Game State Changes** and **Game Events** using this API. **IGameObjectLifecycleSubscriber** – *MachinationsGameAwareObject* **and** *MachinationsGameLayer* implement this. Your game logic/engine should notify \_MachinationsGameAwareObject\_sof **Game Object State Changes** and **Game Object Events** using this API. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://machinations.gitbook.io/machinations-dev-docs/core-concepts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.