Functions

To handle more complex data or logic operations you can add your own javascript functions to adaptor:ex.

The functions chapter in the Glossary shows how to use functions in adaptor:ex games and provides details about all included functions.

This chapter will show you how you can write and add your own javascript functions for your game projects.

Add Functions

Like files and media files, functions are stored in the adaptor:ex data folder games in the respective game folder.

Create one or more javascript files ( .js ) in your game's folder functions containing your functions.

data
├── games
|   └── Playground
│       ├── files
│       └── functions
│           └── myfunctions.js <--
├── log
├── nedb
└── config.json

Directory depth

Functions within the functions folder are registered in a maximum of one level directory depth. That means you can, for example, use subfolders to clone the functions of a git repository, but all .js files that export functions you may want to use, must be at the top level of this subfolder.

The files are loaded into your game as nodejs modules so you need to make your functions available to adaptor:ex using module.exports

async function playerCount(args, {session, game}) {
    all_player = await game.db.players.find({})

    return all_player.length
}

function reverse(args, {session, game}) {
    let reversed = args[0].split("").reverse().join("")
    return reversed
}

module.exports = {
  playerCount:playerCount,
  reverse:reverse
}

If you copy these lines into a new file with the .js extension and move them to the functions folder in your game, you can access two new functions "reverse" and "playerCount" in your game.

You can add as many functions as you want in one file or split the functions across multiple files. The file names can be arbitrary and carry no further meaning.

Write functions

Note

This chapter is far from complete. Contact us if you have any questions at tech@machinaex.de or on the machina commons discord server. We also recommend to a look at the functions included with the adaptor:ex source

You can use almost everything the Nodejs Javascript Runtime has to offer.

To add external libraries that are not included with adaptor:ex, install them globally or in the functions folder of your game so that they are placed inside a node_modules folder in the functions directory.

All the parameters passed by the level session are included in the first argument.

The second argument always contains variables and functions from the adaptor:ex game and session context.

async function playerCount(args, context) {
    all_player = await context.game.db.players.find({})

    return all_player.length
}

function reverse(args, {session, game}) {
    let reversed = args[0].split("").reverse().join("")
    return reversed
}

module.exports = {
  playerCount:playerCount,
  reverse:reverse
}

args contains the parameters specified in the level the function is used. Multiple parameters will be passed as an array.

Note

"args" is always an array when the function is called as variable. Therefore it is recommended to always treat "args" as an array. This way you can use the function in any context.

The second argument context is an Object that contains session and game.

session context

session provides functions and properties related to the session that called the function.

Example:

Print messages in the session context with session.log

function helloWorld(args, {session, game}) {
    session.log('Hello World')
}

game context

game provides functions and properties related to the game in which the session that called the function is running.

Example:

Use the game context to get the correct external link to a file in the adaptor:ex data directory

function fileURL(args, {session, game}) {
    const fileUrl = game.getFileURL(args[0])
}

adaptor context

You also have access to the global adaptor variable that provides functions and properties related to the adaptor:ex server hosting the game with the corresponding session.

Example:

Use the adaptor context to get the version of the adaptor:ex server

function getVersion(args, {session, game, adaptor}) {
    return adaptor.info.version
}