Modding UniBlaster

The major game modes in RetroWar all use our UniBlaster engine. It can be modded in various ways...

Music

To add new songs, simply drop them into the music folder. Currently supported formats are:

Levels

New levels can be created using Tiled.

The format is not yet finalised, but you can load the existing levels into the editor to see how they were made and edit them. See below for how to make a game that uses your new levels.

... tutorial soon ...

Characters

Look in the addons folder and you will see several subfolders. Many of them contain a groovy script which configures one of the UniBlaster games. For instance, take a look at droids/droids.groovy which configures the Droids game.

import uk.me.fantastic.retro.unigame.*
import static uk.me.fantastic.retro.GlobalsKt.*
import static uk.me.fantastic.retro.unigame.PowerupFactory.*
import static GroovyHelpers.*

unigame(
    name: "UniBlaster - Droids",
    description:  "A fast-paced twin stick shooter",
    levels: ["arena1", "arena2", "arena2small",
             "arena21wide", "arenagap", "maze2", "cross"],
    startingCreates: 1,
    crateSpawnTime: 5f,
    crateAnim: Resources.CRATE_METALLIC,
    powerups: [
        new FiringRateAndSpeedUp(10f),
        new AccelerationPlus300(10f),
        new HealthUp(10f, 10f),
        new BlastRadiusUp(3f, 1f),
        new SpreadShot(15f)
    ],
    characterFactory: characterFactory(
        health: 10.0F,
        bulletSpeed: 200.0F,
        knockBack:  0.5f,
        rate: 15.0F,
        maxSpeed: 400.0F,
        acceleration: 500.0F,
        trigger: false,
        anims: Resources.getDROIDS(),
        bulletExplosions: 0,
        bulletBounce: 0.0F,
        bulletAntifriction: 1.0F,
        bulletMomentum: false,
        characterKnockback: 0.3f,
        bulletDamage: 1f,
        bulletLifeTime: 3f,
        anyDirectionEngine: true,
        oneDirectionEngine: false,
        rotation: false
    )
)

This script is written in Groovy, a Java-like scripting language. If you change it, you will change the Droids game in RetroWar. However any changes you make will probably be overwritten next time the game is updated. Therefore you should put your modifications into the mods folder.

Make a new folder mods/mygame. Copy the droids.groovy script into it. (The name of the script file does not matter, but you may rename it.)

Now you will find a new game has appeared on the mods menu - your game.

Unigame Parameters

ParameterTypeDescription
name String Short name displayed in menu
description String Longer text describing game, may contain linebreaks.
levels Array<String> The names of the level files without the file extension. FIXME improve this.
startingCreates Int The number of powerup crates added to the level randomly at the start of the game.
crateSpawnTime Float Interval between spawning of new power-up crates (seconds).
crateAnim Animation<TextureRegion> The animation (or static image) drawn for each power-up crate. There are two pre-defined images you can use: Resources.CRATE and Resources.CRATE_METALLIC FIXME how to create animations
powerups Array<PowerupFactory> A list of powerups. The predefined ones are listed below. Usually they take two arguments: the relative probability of them appearing, and the amount of boost they give the player.
characterFactory characterFactory() See below for the params.

Powerups

FIXME how to create new powerups, and standardise these ones a bit more

Current Powerups:

CharacterFactory Parameters

ParameterTypeDescription
health Float Health points the player starts with
knockBack Float How powerful the player's bullets are at knocking things they collide with, usually in range 0.0...1.0.
bulletSpeed Float Speed of player's bullets, in pixels per second.
rate Float Firing rate of player's gun, in bullets per second.
maxSpeed Float Cap on how fast the player can move, in pixels per second.
acceleration Float How quickly the player can change speed, in pixels per second per second. Set this high to make movement feel responsive.
trigger Boolean Whether the player's gun requires a button press to fire (else it just fires automatically).
anims
bulletExplosions Integer The size of the explosion when the bullet hits something. Set to zero for no explosion. Unit is map tiles.
bulletBounce Float How much velocity is maintained in primary axis of a collision with a level block. Value of 1 means no velocity is lost, i.e. collision is completely elastic.
bulletAntifriction Float how much velocity is maintained in secondary axis of a collision with level block. Value of 1 means no velocity is lost, i.e. collision is completely elastic. For newtonian physics, set bounciness and antifriction to the the same value, i.e the coefficient of restitution
bulletMomentum Boolean Whether the player's velocity is passed on to his bullets at time of firing.
characterKnockback Float Amount player is knocked back when hit by bullets. Usually in range 0.0 ... 1.1.
bulletDamage Float How much health of target is reduced when hit by player's bullet.
bulletLifeTime Float How long bullets last, in seconds.
anyDirectionEngine Boolean Whether to give player a standard newtonian engine that can accelerate in any direction.
oneDirectionEngine Boolean Whether to give player an engine that can only accelerate straight forwards.
rotation Boolean Whether the player sprite is allowed to rotate.

There's also a subclass that sets up Bomber type grid movement and only takes a subset of the parameters, like this

 characterFactory: bomberCharacterFactory(
        health:  100.0F,
        maxSpeed: 100.0F,
        acceleration:  1000.0F,
        characterKnockback:  0.7f
    )