Creating new effects

Effects has as base the following schema:

{
    "additionalProperties": false,
    "javaType": "es.eucm.ead.schema.effects.Effect",
    "type": "object",
    "description": "Effects define elements that affects/changes the game state or how the element is rendered."
}

Each new effect must extend this schema.

{
    "additionalProperties": false,
    "extends": {
        "$ref": "effect.json"
    },
    "javaType": "es.eucm.ead.schema.effects.ConsoleLog",
    "properties":{
        "text": { 
            "type": "string",
            "description": "Message to log"
        }
    }
    "type": "object"
}

When the schema is regenerated, we'll have a new class ConsoleLog. We can define a ConsoleLog effect in json like this:

{
     class:consolelog,
     text:"Hello world"
}

Now, we need to set its behavior in the engine.

All effects in the engine extends EffectEngineObject. This class define two abstracts methods, one for initializing the effect and another to get it executed:

@Override
public void initialize(Effect schemaObject) {
  // Initialize this EffectEngineObject with the given Effect.
  // Immediate effects (e.g. [ChangeRendererEngineObject] (https://github.com/e-ucm/ead/blob/master/engine/core/src/main/java/es/eucm/ead/engine/effects/ChangeRendererEngineObject.java) ) should place all the logic here.
}

@Override
protected boolean delegate(float delta) {
 // Code that updates the effect according to the "delta" elapsed. Immediate effects may just do nothing here, since they do not need to be updated;
 // Return true if the effect has already finished, false if it should be kept running. Immediate effects always return true.
}

In this case, we want that our effect logs a message to the console (pretty impressive, huh?)

public class ConsoleLogEngineObject extends EffectEngineObject<ConsoleLog> {

        private String text;

        @Override
        public void initialize(ConsoleLog element) {
                this.text = element.getText();
        }

        @Override
        protected boolean delegate(float delta) {
                Gdx.app.log("effect", text);
                // Returns true if the effect has finished, false if it needs more updates to finish
                return true;
        }
}

Finally, we need to tell the engine that there's a relation between ConsoleLog and ConsoleLogEngineObject. We do that by modifying binds.json.

ConsoleLog follows the eAdventure naming convention for effects. That means, the schema object with name XXX is defined in package es.eucm.ead.schema.effects and its respective engine object XXXEngineObject is in es.eucm.ead.engine.effects. For that reason, we just need to add a single line below [es.eucm.ead.schema.effects, es.eucm.ead.engine.effects] in bindings.json, and the engine will be smart enough to do the rest:

    ...
    [es.eucm.ead.schema.effects, es.eucm.ead.engine.effects],
    ...
    [ApplyEffectToTags],
    [ConsoleLog],

When the convention name above described is not followed it is necessary to use add a second parameter to the new binding definition. For example, if we refactor ConsoleLogEngineObject and rename it to ConsoleLogEO, then the binding should look like this: [ConsoleLog, ConsoleLogEO],

This bind also sets automatically the alias of class ConsoleLog to consolelog, used in the class attribute in the json definition. This attribute is necessary while reading the json.