MGK-008 Lore Packages

[jwulf]

User Story

As a user, I can publish a package to GitHub or to npmjs.com, and other users can install that package and have it automatically enrich their Play App IntelliSense, as well as be available in Magikcraft as magikcraft.io.lore.${username}...

Background

In earlier iterations of Magikcraft, we allowed developers to enrich the Magikcraft API at runtime by registering helper functions to the magik.Lore.${username} namespace. This was very popular and empowered an exciting, creative dynamic. We want to make this a feature of Magikcraft again, at scale, by leveraging NPM and GitHub and allowing developers to create their own schools of Magik.

Lore vs normal packages

Lore packages

• Are loaded into a custom namespace on the global magikcraft.io object: magikcraft.io.lore.
• When you supply a *.d.ts typings file, the Play App Spellbook Intellisense is updated to provide autocomplete for your lore.

Normal packages

• Must be required in via import (TypeScript/ES6) or require (ES5)
• Can provide autocomplete in Visual Studio Code, but not in the Play App.

Feature Description

This is a specification by convention for a package format.

An example package suitable for use as a template is https://github.com/Magikcraft/magikcraft-lore-_template.

An MGK-008 Lore Package should export a _lore object containing metadata about the lore, and the lore to be loaded.

The _lore object should have the following shape:

{
    namespace: string;
    loreToLoad: [
        {
             name: string;
             code: function;
             cost: number;
        }
    ]
}

Here's an example:

{
    namespace: 'sitapati',
    loreToLoad: [
        {
             name: 'sendMessage',
             code: require('./lib/sendMessage'),
             cost: 0
        },
        {
            name: 'where',
            code: require('./lib/where'),
            cost: 0
        }
    ]
}

This results in the following globally available functions at run-time:

magik.lore.sitapati.sendMessage();
magik.lore.sitapati.where();

Your lore function code must be Nashorn-compatible ES5.1. You can use the ES5 transpilation target of Babel or TypeScript, or write directly in ES5.

Each of your lore functions should have the following signature:

(canon: ICanon) => (...args) => any;

It is a function that takes the ICanon object, and returns your lore function. When your lore is loaded into Magikcraft, the API loader will inject the canon object. The canon object provides your lore function with a closure containing the following:

export interface ICanon {
    sender: any,
    plugin: any;
    http: any;
}

sender is a reference to the player in whose engine your code is executing. For example, this is how you write a sendMessage lore to send a message to the player's console using the Bukkit Player.sendMessage method:

function _sendMessage(canon) {
   return function sendMessage(msg) {
        canon.sender.sendMessage(msg);
    }
}

plugin is a reference to org.bukkit.plugin.Plugin.

function _where(canon) {
    return function where() {
        var magik = magikcraft.io;
        canon.plugin.getServer().getOnlinePlayers().forEach(function(player) { 
            magik.dixit('§6' + player.getName()  + ': §a' + player.getLocation().getWorld().getName());
        });
    }
}

Out of Scope

Great things that can be done in version 2:

Acceptance Criteria

The following need to function to consider this feature complete:

User Acceptance Test Plan

Here is the process for testing this feature:

End-User Documentation

[Docs that can be copypasta to the user docs]

[jwulf]

Lore loader

[jwulf]

This issue was moved to Magikcraft/magikcraft-release-notes#9