Mini-Games

From wiki
Revision as of 12:04, 3 May 2019 by Callum (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Mini-Games are small, moddable, self-contained javascript games that can be played by interacting with an arcade machine (or specifically, tiles that use the "staxel.entityAction.PlayGame" interactActionTrigger). Programming knowledge is required.


Getting Started

All mini-games are referenced through the miniGames.config file located in the root content folder. Each mini-game must have the following:

  • code - The code used to refer to a particular mini-game.
  • gameSource - The local path to a .js file containing the source code for the mini-game.
  • icon - (optional) The local path to a .png image that will be displayed in the mini-game selection list.

To add your own mini-game without modifying miniGames.config (recommended for public mods), first, create a .patch file with contents similar to the following:

{
  "file": "miniGames.config", // name of the file to "patch"
  "patch": {
    // the miniGamesList from miniGames.config will be merged with our one here
    "miniGamesList": [
      {
        "code": "my.mod.code",
        "icon": "mods/myMod/Icon.png",
        "gameSource": "mods/myMod/myMiniGame.js"
      }
    ]
  }
}

Once the patch file is created the game itself can be added to the source file mentioned in "gameSource" above. In this example, the file should be called "myMiniGame.js" inside the "mods/myMod" folder. Additionally, if an icon was specified, an image should be added as well.


Mini-Game API

MiniGameHandler

All API functions are called from an object that must be named MiniGameHandler. The following members are initialised automatically and can be used immediately:

  • canvas - The canvas element used to render to.
  • defaultFont - The current font name in use by the current language. Defaults to "Arial" if no font is currently in use.
  • defaultFontSize - The current font size in use by the current language. Defaults to "20pt".
  • playSound(soundCode) - Plays a sound specified by soundCode (String).
  • loadImage(imagePath, width, height) - Loads an image from disk specified by imagePath (String), or from the cache if available. width and height specify the size of the image. Returns a future Object that can be used to get the resulting image. See #ImageFuture.
  • getTranslations(codes) - Loads translations from the Staxel Client specified by their codes from codes (String Array). Returns a future Object that can be used to get the resulting translations. See #TranslationsFuture.
  • exit() - Call this function if you would like to close the mini-game. Also called automatically if the mini-game needs to be closed externally. Proceeds to call the stop() function.

The following members must be defined (or may be optional):

  • renderingType() - Called before the call to start(). Return "pixelated" for pixelated rendering, or an empty string to default rendering.
  • start() - Called when the game is ready to start. Use this to initialise any required state.
  • stop() - Called during a call to exit(). Use this function to clean up any resources.
  • update() - Called when Staxel is ready to render a frame for the mini-game. Gets called as often as possible (approximately 60 times per second). Use this function to update mini-game logic and render to the canvas.
  • pause() - Called when Staxel gets paused or if the player presses the Back interface key/button (Esc by default on keyboards). Used externally and should not be used to pause a mini-game manually.
  • resume() - Called when Staxel gets resumed or if the player presses the Continue button in the pause menu. Used externally and should not be used to pause a mini-game manually.
  • pressAccept() - Optional. Called when the player presses the Accept interface key/button.
  • tabPrevious() - Optional. Called when the player presses the TabPrevious interface key/button.
  • tabNext() - Optional. Called when the player presses the TabNext interface key/button.
  • pressPrevious() - Optional. Called when the player presses the Previous interface key/button.
  • pressNext() - Optional. Called when the player presses the Next interface key/button.
  • pressUp() - Optional. Called when the player presses the Up interface key/button.
  • pressDown() - Optional. Called when the player presses the Down interface key/button.
  • pressLeft() - Optional. Called when the player presses the Left interface key/button.
  • pressRight() - Optional. Called when the player presses the Right interface key/button.
  • releaseUp() - Optional. Called when the player releases the Up interface key/button.
  • releaseDown() - Optional. Called when the player releases the Down interface key/button.
  • releaseLeft() - Optional. Called when the player releases the Left interface key/button.
  • releaseRight() - Optional. Called when the player releases the Right interface key/button.

ImageFuture

An ImageFuture is an Object with two members:

  • element - The resulting image element loaded. This may be null until complete is true.
  • complete - True if the image has finished loading. False otherwise.

TranslationsFuture

A TranslationsFuture is an Object with two members:

  • translations - The resulting translation strings returned as an array. This may be null until complete is true. This will be in the same order as the translation codes given to getTranslations.
  • complete - True if the translations have been loaded. False otherwise.


Debugging

Mini-games can be debugged via a Chrome debugger. Create a file within the same folder as the Staxel.Client.exe executable called "core.config" and fill it with the following to enable ui (and mini-game) debugging:

{
  "ShowConsoleClient": true
}

Optionally, simply create an empty file called "showconsole.txt" within the same folder as the Staxel.Client.exe executable for the same effect.

Once the Staxel Client is running and showing its debug window, open the mini-game menu (by interacting with an Arcade Machine), open a Chrome page, and enter "http://localhost:8086/" into the URL search box.


Example

For more examples see the existing mini-games located in "staxel/ui/js/MiniGames".

var MiniGameHandler = {};
var MyGame = {
  paused: false
};

MiniGameHandler.renderingType = function() {
    return "pixelated";
};

MiniGameHandler.start = function() {
    // set any state here
    MyGame.paused = false;
};

MiniGameHandler.stop = function() {
    // clean up any resources here
};

MiniGameHandler.pause = function() {
    MyGame.paused = true;
};

MiniGameHandler.resume = function() {
    MyGame.paused = false;
};

MiniGameHandler.pressAccept = function() {
    // handle Accept press here
};

MiniGameHandler.update = function() {
    if (MyGame.paused)
        return;
    // handle any update logic here

    // render to the canvas here
};