Tutorial: How to make you own Tag in JS

By "making your own tag", it usually means "make your own tag action, so you can create tag for it".

Every "command" is represented by a TagAction object, and it contains an action, and rules for arguments.

Making an action

Here is an example of making a [hello] tag.

// plugin/hello.js
Tag.actions.hello = new TagAction({
    action: function(args) {
        // `args` is an object with all the attributes from KAG
        console.log("Hello from JS! "+args.name);
        return 0;
    }
});

You can load the JS file and run it like this:

[o2_loadplugin module="hello.js"]
[hello name="Foo"] ;You can pass the `name` parameter to JS like this

You should be able to see "Hello from JS! Foo" in the console.

Every action has to return a number, the final line in the above example return 0; means the action ends immediately apart from 0, you can return other values:

• 0 - Tag action ends immediately
• 1 - Tag action needs to take some time (for example loading an image asynchronously)
• 2 - Tag action never ends (e.g. the [s] tag that stop forever)

If you return 1;, you will need to end the tag action by calling this.done() when it finishes.

This is an example of a tag that continues after 1 second.

Tag.actions.wait_1_second = new TagAction({
    action: function(){
        setTimeout(()=> this.done(), 1000);
        return 1;
    }
});

before
[wait_1_second]
after

You should able to see there is an 1 second gap between "before" and "after".

Reading arguments

You can pass a rules object to the TagAction and the argument, attributes in KAG will be validated before passing to your action. The advantage of providing a rules object is that error message is generated automatically when there is a type mismatch.

The following is an example of a tag that hide, then show the layer for some time.

Tag.actions.hide_then_show = new TagAction({
    rules: {

        // "LAYER" type automatically looks for the layer from string like "message0", "1", "base", and return an object for the layer
        layer: {type:"LAYER", required:true},

        // You can also use regular expression for validation
        page: {type:/fore|layer/, required:true},

        // You can also set a default value for an attribute
        time: {type:"TIME", defaultValue: 1000 }
    },
    action: function(args) {
        args.layer[args.page].visible = false;

        setTimeout(()=> {
            args.layer[args.page].visible = true;
            this.done();
        }, args.time);

        return 1;
    }
});

The tag can then be used like this:

[hide_then_show layer=0 page=fore]
; Good

[hide_then_show layer=99999 page=blah time=2000]
; Error, `layer` not found, `page` not match

[hide_then_show layer=base page=back time="1:00"]
; Good, "TIME" type accepts "minute:second" notation

o2engine supports the following types:

• STRING
• BOOLEAN - convert "true", "false" to true/false
• INT
• FLOAT
• LAYER
• IMAGE_LAYER
• MESSAGE_LAYER
• COLOR - convert "0x112233" to "#112233"
• TIME - convert "1:22:33", "1:22" to millisecond
• OBJECT
• RUNNABLE (function or string to eval)