All Modding references in a single article
Standard Modding Interface, you can see the minimap of the mod in the bottom right corner while the mod is running
Starblast Modding interface can be found here: https://starblast.io/modding.html (ECP required)
Starblast Modding interface allows you to create custom mods for Starblast. The interface is made of a code editor window, on the left, and a console window, on the right. The code editor is where you type the JavaScript code for your mod. The console is where you can type commands to start your mod, stop it or interact with it while it is running.
Main programming language used in this interface is JavaScript (ECMAScript)
In newer versions of browsers' updates, you can't use the Modding Client in incognito mode anymore as they restrict some incognito features which are used by the editor.
And make sure to read all of these from the start to the end so that you won't miss any important info!
In the Mod Code window, type the code for your first mod:
this.options = {
root_mode: "survival",
map_size: 30
};
this.tick = function(game) {
};Once your mod code is ready, in the console, start by selecting your preferred region for modding using the command region <region name>. For example with Europe:
> region Europe
Region set to Europe
> █
(Currently modding is only available in these 3 zones: Europe, America, Asia)
Then to start running your mod, type command start:
> start
Mod started
https://starblast.io#1234@12.34.56.78:2000
Use 'test' to open game frame for testing
> █
As instructed by the console, you may want to open a test window to join your modded game with a Starblast client. Type test:
> test
> █
This is one of the most important things you need to keep in your mind!
Why? Because that's nuances of how browsers work.
Browsers slow down all javascript in non-active tabs in order to decrease the CPU processes.
For some mods (e.g Battle Royale), it doesn't matter like with ship tree and options only,
but for other mods where some logic in tick function or events - it will affect them A LOT!
Ticks start to work slower and slower...
Soon everything will be lagging in game; any reactions on mod buttons, any mod logic like spawning something in tick, etc.
And... depending on mod complexity it can CRASH THE ENTIRE MOD - locally, server will continue to work so game will still run but without mod logic anymore.
So, always keep the mod editor tab online or you may have unpredictable results!
Also, you need to have a stable internet connection if you don't want your mods becoming laggy.
You can stop your mod anytime by using the command stop. Note that this will kill the game and disconnect all connected players:
> stop
Mod stopped
> █
Print any values to the terminal; can be used in both mod code (after mod started) and terminal
Syntax: echo(<item>)
> echo("Message from terminal!")
Message from terminal!
> █
Clear the terminal, only available in the terminal
Syntax: clear
Display help message inside the terminal, terminal use only
Syntax: help
Stored in this.options is a data structure where you can set options for your custom modded game. These options are used for initializing the game when you start your mod. Changing them while the mod is running does not affect the game.
You can import ships made within the Starblast Ship Editor. Use "Mod Export" feature to export a JavaScript code snippet for the modding interface. Then paste this snipped in the coding window and add this:
var myship_101 = "{ … … <this is your exported ship code> …";
var ships = [myship_101]; // add your ship to an array of ship
this.options = {
root_mode: "survival",
ships: ships, // specifying a list of ships to complement / replace existing ships
reset_tree: true, // set to true if you want to remove the original ship tree, false if you just want to replace some of the ships
map_size: 30
};
this.tick = function(game) {
};Then run your mod. If your ship is set to level=1 model=1, your ship will replace the Fly. You can replace other ships in the tree in a similar way, using reset_tree: false. Or you can remove the original ship tree completely and provide a whole new one using reset_tree: true.
The vocabulary used for the emote-chat system can be customized by setting the field vocabulary in the game option
as follows:
var vocabulary = [
{ text: "Hello", icon: "\u0045", key: "O" },
{ text: "Bye", icon: "\u0046", key: "B" },
{ text: "Yes", icon: "\u004c", key: "Y" },
{ text: "No", icon: "\u004d", key: "N" },
{ text: "Flower", icon: "\u{1F33B}", key: "F" },
{ text: "Snowman", icon: "\u26c4", key: "M" },
{ text: "Shark", icon: "\u{1F988}", key: "S" },
{ text: "Ghost", icon: "\u{1F47B}", key: "G" }
];
this.options = {
vocabulary: vocabulary,
// ...
};This allows using Starblast built-in emote icons, which are listed here for reference: https://starblast.io/glyphs.html
You can also use unicode icons, here is a good source for reference: https://unicode.org/emoji/charts/full-emoji-list.html
Note that wide unicode characters (using more than 2 bytes) requires a specific Javascript syntax as shown in the example above (example: \u{1F47B})
You can create a custom map of asteroids. This allows creating a maze for example. The custom map you provide is actually a JavaScript character string that is used to "paint" the map.
For example:
var map =
"999999999999999999999999999999\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"99 99\n"+
"999999999999999999999999999999" ;
this.options = {
custom_map: map,
map_size: 30
}In the example above, 9 sets the biggest size of the asteroid. You can use smaller values for adding smaller asteroids to the grid. Any value other than a digit will be interpreted as no asteroid. If your map_size is set to 30, make sure to create 30 lines and 30 columns, or you may get unpredictable results.
Note: Use "" for blank custom map
You can use Online Map Editor (a community tool) to create, edit and export maps.
Most of the options are inherited from the usual custom games. A few more options have been added, specifically for modding (top of the list):
| Option | Expected data type | Description | Default value (if omitted) |
|---|---|---|---|
| root_mode | string | The mod to inherit from: "survival", "team", "invasion", "deathmatch", "battleroyale" or unspecified (other values) | unspecified |
| reset_tree | boolean | Set to true to remove the original ship tree | false |
| ships | array<string> | An array of ships to add to the tree | None |
| map_size | integer | Size of the map, range from 20 to 200, even value only | 100 (survival) 80 (team and Battle Royale) 60 (unspecified) 30 (Invasion) 20 (deathmatch) |
| soundtrack | string | "procedurality.mp3", "argon.mp3", "crystals.mp3", "red_mist.mp3", "civilisation.mp3", "warp_drive.mp3" or none (other values) | "crystals.mp3" (invasion and Batte Royale) "argon.mp3" (deathmatch) "procedurality.mp3" (others) |
| max_players | integer | Players limit of the game, from 1 to 240 | 70 (team) 60 (survival) 40 (unspecified) 30 (Battle Royale) 20 (deathmatch) 6 (invasion) |
| crystal_value | float | Crystal multiplier applied to crystals dropping from destroyed asteroids, from 0 to 10 | 2 (team) 0 (deathmatch and Battle Royale) 1 (others) |
| lives | integer | Number of lives, from 1 to 5 | 4 (team) 1 (deathmatch and Battle Royale) 3 (others) |
| maxtierlives | integer | number of lives (from 1 to 5) when player reaches ships with the highest level (defined in max_level option) |
0 (team and deathmatch) 1 (Battle Royale) 3 (others) |
| max_level | integer | Max level you can reach, from 1 to 7 | 7 |
| friendly_colors | integer | Serves to define teams; how many teams (or 0, maximum 5) | 3 (team) 1 (invasion) 0 (others) |
| map_name | string | Name of the map | Auto-generated name |
| survival_level | integer | Level which triggers survival mode (8 for no trigger, 2 minimum) | 7 (survival) 8 (others) |
| starting_ship | integer | Enter desired ship code: 101, 201, 404, etc. | 101 |
| starting_ship_maxed | boolean | starting ship is maxed | false |
| asteroids_strength | float | The strength of the asteroids compared to their normal states, 0 to 1000000 | 5 (deathmatch) 0.5 (Battle Royale) 1 (others) |
| friction_ratio | float | friction ratio of the game (0 to 2) | 1 |
| strafe | float | strafing speed factor, from 0 to 1 | 0 |
| speed_mod | float | Speed of the mod, from 0 to 2 | 1.25 (deathmatch) 1.2 (survival and team) 1 (others) |
| rcs_toggle | boolean | Enable RCS feature for ships | true |
| map_id | integer | Seed (ID) of the auto-generated map, from 0 to 9999 | Game ID |
| map_density | float | Density of the map, from 0 to 2 | None |
| weapon_drop | float | Probability that an asteroid will drop a weapon, from 0 to 10 | 0 |
| crystal_drop | float | percentage of gems can be collected when a ship drain gems, from 0 to 1 | 0.5 (deathmatch) 1 (others) |
| release_crystal | boolean | allow [V] to release gems |
true (team) false (others) |
| mines_self_destroy | boolean | Mines will self-destruct after a while | true |
| mines_destroy_delay | integer | all landed mines will be destroyed after this interval if no enemies triggered the mines (in ticks) minimum 0, no actual maximum limit |
3600 (Battle Royale) 18000 (others) |
| healing_enabled | boolean | Enable healing feature | true (team) false (others) |
| healing_ratio | float | Healing ratio to actual laser damage, from 0 to 2 | 0.5 (team) 1 (others) |
| shield_regen_factor | float | Shield regeneration multiplier to natural regeneration of ships, minimum 0, no actual maximum limit | 1 |
| power_regen_factor | float | Power (Energy) regeneration multiplier to natural regeneration of ships, minimum 0, no actual maximum limit | 1 |
| invulnerable_ships | boolean | Ships are invulnerable | false |
| weapons_store | boolean | Allow access to the weapon store | true |
| radar_zoom | float | Radar zoom ratio. Set value to 1, 2 or 4 (recommend values which are powers of 2) | 2 |
| auto_refill | boolean | Collecting an energy or shield pill immediately refills energy or shield, otherwise the collected pill is added to the active weapons | false |
| projectile_speed | float | Affects the speed of rockets, missiles and torpedoes; use 1 for default speed (minimum 0, no actual maximum limit |
1 |
| choose_ship | array<integer> | e.g. setting to [301,302,303] will let player choose a ship from these 3 ships before entering the game |
None |
| collider | boolean | Enable collisions of player ships with anything | true |
| Option | Expected data type | Description | Default value (if omitted) |
|---|---|---|---|
| survival_time | float | When to trigger survival mode (in minutes): 0 to disable survival time trigger from 1 to 600 to set the survival trigger time |
60 |
| bouncing_lasers | float | Must be a value between 0 (no bounce) or 1 (bounce retains 100% of the laser damage) Note: This feature is planned to be applied to all root modes in the near future |
0.9 |
| Option | Expected data type | Description | Default value (if omitted) |
|---|---|---|---|
| hues | array<integer> | Hue numbers for teams, with the same amount of elements as used for friendly_colors |
Auto-generated hues |
| station_regeneration | float | factor to apply to station shield regen, from 0 to 2 | 1 |
| station_size | integer | size of the stations; integer from 1 to 5 | 2 |
| station_crystal_capacity | float | factor to apply to the station crystal capacity, from 0.1 to 10 | 1 |
| station_repair_threshold | float | part of the station crystal capacity that must be refilled to repair a module, from 0 to 1 | 0.25 |
| auto_assign_teams | boolean | allow assigning players to a specific team, otherwise let them choose the team themselves | false |
| all_ships_can_dock | boolean | allow ships of Tier higher than base station normally lets in, to enter depots | false |
| all_ships_can_respawn | boolean | allow ships of Tier higher than base station normally lets in, to respawn from spawn ports, otherwise randomly on map | false |
| Option | Expected data type | Description | Default value (if omitted) |
|---|---|---|---|
| ship_groups | array<string> | An array containing some arrays, each of them representing one ship group (by name) available for selection See the example below. The longer the array is, the lower chance for each ship group being available in a single match |
See Deathmatch for a list of default ship groups. The mod won't run if reset_tree option is set to true without manually specifying the ship groups.Please note that the ship groups will be automatically set to only U-Sniper if map_name are set to "Battle of Titans". Please see here for more information |
Example:
ship_groups: [
["U-Sniper","Howler"],
["Crusader","Pioneer"]
]Found in this.tick is a JavaScript function that is called 60 times per second. In this function’s body, you will be able to code specific actions that your mod needs to take automagically while the game is running. This function can be modified while the modded game is running and the changes will apply automagically.
Your mod can receive events through the function this.event:
this.event = function(event,game) {
switch (event.name)
{
case "ship_spawned":
if (event.ship != null)
{
shipJustSpawned(event.ship) ;
}
break ;
}
} ;| Event name | Description | Additional event fields |
|---|---|---|
| ship_spawned* | A ship just spawned in game or respawned | event.ship |
| ship_destroyed | A ship was just destroyed | event.ship, event.killer |
| alien_destroyed | An alien was just killed | event.alien, event.killer |
| asteroid_destroyed | A movable asteroid was just destroyed (this event won't trigger for non-movable asteroids) | event.asteroid, event.killer |
| collectible_picked | A ship just picked a collectible item | event.collectible, event.ship |
| ui_component_clicked | A ship just clicked a (clickable) UI component on their screen | event.ship, event.id |
Note: * means that this event only works with unspecified root_mode (root_mode: "")
All entities and objects in the game are moving on a 2D plane called "map"
Map can be painted with asteroids using this.options.custom_map and set size by this.options.map_size (even value from 20 to 200)
All Modding commands relating to coordinates will be visualized on this map
| Axis | Direction in user screen |
|---|---|
| X | left to right |
| Y | bottom to top |
| Z | map "depth", only used for setting 3D Objects |
The map is divided into "grids".
A Grid is a 10x10 square area which can only contain 1 static asteroid (which equals to 1 character to "paint" the map in this.options.custom_map)
map_size is the number of grids along each dimension, which means that the number of grids in the map is calculated by the formula map_size2.
For example: map_size being 30 means that there are 30 grid length along the X Axis and Y Axis, and 302 = 900 grids total in the map
Map center (x:0, y:0) is located in the Sun
Based on the Grid definition, we have:
Each Axis will have map_size / 2 grids length in both negative and positive part
Because each grid is a 10x10 square, the boundary of each part is map_size / 2 x 10 = map_size x 5
Means that each Axis varies from -map_size x 5 to map_size x 5
For example: with map_size = 30, each Axis in the map varies from -300 (-60x5) to 300 (60x5)
Can be accessible through game.step; an integer presenting the game's duration
The unit of this value is tick, where 1 tick = 1/60 seconds
Which means that 60 ticks = 1 second, 120 ticks = 2 seconds and so on.
This code uses to set the first ship in the list to the center of the map in the first minute of the mod and reset its crystals every 5 seconds (assume that there is one ship staying from the start of the mod):
this.tick = function (game)
{
if (game.step == 3600) { // 1 minute = 60 seconds * 60
game.ships[0].set({x:0,y:0}); // Center teleport
}
if (game.step % 300 === 0) { // 5 seconds * 60
game.ships[0].set({crystals: 0}); // Reset crystals
}
}You can access the list of ships (players) through the array game.ships
You can also find a ship with a specific id using game.findShip(id), which returns an object representing the matched ship or null (if no ships are matching the provided id)
You have read access to the ship’s main fields and options:
| Field | Description |
|---|---|
| id | A unique identifier for the ship |
| game | Points to the global game object |
| x | X coordinate |
| y | Y coordinate |
| vx | Velocity vector X component |
| vy | Velocity vector Y component |
| r | Rotation angle of the ship (in radian) |
| name | player's name |
| alive | Whether the ship is alive or destroyed |
| type | Ship type code (e.g. 101) |
| stats | Ship current stats upgrades, compiled into a single integer. For example: 10012301 means the 8 stats upgrade levels are 1,0,0,1,2,3,0 and 1 |
| idle | tells if the ship is in idle status or not |
| team | the id of the team this ship is in |
| score | player's score |
| shield | current shield value |
| generator | current generator value |
| crystals | current crystals value |
| healing | whether the ship's lasers are in healing mode or not |
You can set different options on the ships. For example:
> game.ships[0].set({x:0,y:0});
> █
Will move the first ship in the list to the center of the map
List of accepted options when using ship.set:
| Option | Description | Server response error message (if improper) |
|---|---|---|
| x | X coordinate | Wrong coordinate |
| y | Y coordinate | Wrong coordinate |
| vx | Velocity vector X component | Wrong coordinate |
| vy | Velocity vector Y component | Wrong coordinate |
| invulnerable | Use to set the ship invulnerable for X ticks (e.g. 60 for one second invulnerability) | Wrong invulnerable time |
| type | changes the type of ship (use the ship code, e.g. {type:403} ) |
None |
| angle | changes the direction the ship is facing | Wrong angle |
| score | sets player's score | Wrong score |
| idle | set to true to force the ship to stay idle (and false to revert) | None |
| shield | sets the value of the shield | Wrong shield value |
| generator | sets the value of the generator | Wrong generator value |
| healing | sets ship's lasers mode to healing (true or false) | None |
| crystals | sets ship's crystal amount | Wrong crystals |
| stats | set the stats upgrades of the ship | None |
| kill | Set kill: (any "truthy" value, e.g: true) to destroy the ship |
No violation |
| team | Changes the team this ship belongs to (in range [0-X] where X is teams - 1) | None |
| collider | Change the ship's collider (the ship can interact with other objects in-game or not), must be true or false |
None |
| hue | Sets the colour of the ship (range [0-359]) |
None |
You can send the ship to intermission (a screen with results, offering to respawn). This screen allows you to display custom results information:
> game.ships[0].intermission({"Best Achievement":"Managed to run the mod","Score":1234});
> █
You can also trigger the gameover screen for any given ship. Here again, you can pass results information to pass on to the player:
> game.ships[0].gameover({"Rating":"Can do better","Score":1234});
> █
You can have the flight instructor send instructions to the player. For this find the player's ship and use:
> ship.instructorSays("Hello!")
> █
You can hide the instructor window using:
> ship.hideInstructor()
> █
You can later show it again using:
> ship.showInstructor()
> █
A second, optional parameter allows you to choose which one of the instructor characters will talk to the player. Example:
> ship.instructorSays("Here is your report, Commander","Maria")
> █
| Lucina | Klaus | Maria | Kan | Zoltar |
|---|---|---|---|---|
 |
 |
 |
 |
 |
The mod can create custom UI components that will show up on the player’s screen. This is done by calling setUIComponent on the ship - passing in a component descriptor.
For example:
> ship.setUIComponent({
id:"myid",
position:[0,0,25,25],
clickable: true,
shortcut: "X",
visible: true,
components: [
{ type:"box",position:[0,0,100,100],fill:"#456",stroke:"#CDE",width:2},
{ type: "text",position: [0,0,100,50],color: "#FFF",value: "My Text"},
{ type: "player",id: 1, position: [0,0,50,50],color: "#FFF"},
]
})
> █
Here is the list of UIComponent's accepted options:
| Option | Description | Default value (if omitted) |
|---|---|---|
| id | a unique identifier for this component, mandatory | None (component won't be set) |
| position | expressed in percentage of the main screen, the position of the component [x,y,width,height]. Example: [45,45,10,10] creates a component in the center of the screen, in which width and height are 10% of the screen width and height. |
Client-based positions ("radar_background" and "scoreboard" id, see this section)[0,0,100,100] (others) |
| visible | Whether the component is visible or not. Resend the same data with visible set to false to hide the component | true |
| clickable | Whether this component can be clicked or not | false |
| shortcut | When the component is clickable, a keyboard shortcut allowing to trigger the click event | None (no shortcuts) |
| components | gives a list (array) of graphical features to render within the component, which will be described below | Empty array ([]) |
| Option | Description | Default value (if omitted) |
|---|---|---|
| type | type of the subcomponent currently supported: "round", "text", "box" or "player" |
None (subcomponent won't be rendered) |
| id ("player" type only) | id of the player associated with the subcomponent, which will be disapleyd as their name and badge (if exists) in the rendered subcomponent | None (blank player info) |
| position | positions of the subcomponent, formatted as [x,y,width,height]that subcomponent are meant within the main component coordinates |
None (subcomponent won't be rendered) |
| value ("text" type only) | value of the text subcomponent, e.g value:"Sample text" |
Empty string ("") |
| color | text color of the subcomponent, this can be a string with any color formats (hex, hsla, rgb, etc.), e.g "#fff" |
Black (with opacity 1) |
| fill | background color of the subcomponent, same format as the color property |
Black (with opacity 0) |
| width | width of the subcomponent's border One unit of this value equals (1 / (End user screen's pixel density)) CSS pixels (px) |
0 |
| stroke | border color of the subcomponent, same format as the color property |
Black (with opacity 0) |
| align | alignment of the texts inside the subcomponent "left", "right" or "center" only |
"center" |
The example below creates a warp button for every player, which can be clicked and results in the ship warping to another random location, adding 3 seconds invulnerability to it:
Full example: https://github.com/pmgl/starblast-modding/blob/master/examples/warp_button.js
var warp_button = {
id: "warp",
position: [2,50,8,14],
clickable: true,
shortcut: "W",
visible: true,
components: [
{ type:"round",position:[0,0,100,100],fill:"#456",stroke:"#CDE",width:2},
{ type: "text",position:[10,35,80,30],value:"WARP",color:"#CDE"},
{ type: "text",position:[20,70,60,20],value:"[W]",color:"#CDE"}
]
};
var warpShip = function(ship) {
x = (Math.random()-.5) * ship.game.options.map_size*10 ;
y = (Math.random()-.5) * ship.game.options.map_size*10 ;
ship.set({x:x,y:y,vx:0,vy:0,invulnerable:180}) ;
} ;
this.tick = function(game) {
if (game.step%60==0) // ensure this is done only once per second
{
for (var i=0;i<game.ships.length;i++)
{
var ship = game.ships[i] ;
if (!ship.custom.warp_button_installed)
{
ship.custom.warp_button_installed = true;
ship.setUIComponent(warp_button);
}
}
}
} ;
this.event = function(event,game) {
switch (event.name)
{
case "ui_component_clicked":
var ship = event.ship ;
var component = event.id ;
if (component == "warp") // check that this is our component "warp"
{
warpShip(ship);
}
break ;
}
} ;The built-in scoreboard or radar can be replaced by your own custom scoreboard/radar component. As soon as an UI component with id "scoreboard" or "radar_background" is created, you will be responsible for updating the scoreboard/radar. Your custom scoreboard/radar component does not have to include a position because it will automatically fill the area already reserved for the perspective UI Component.
You can use game.setUIComponent({ options }) to set the UI to all current players in the game
Syntax: ship.emptyWeapons()
You can access the list of aliens through the array game.aliens
You can also find an alien with a specific id using game.findAlien(id), which returns an object representing the matched alien or null (if no aliens are matching the provided id)
To create an alien, use game.addAlien({ options })
List of accepted options:
(Note: Server will respond with Incorrect data when at least one input property value is improper)
| Option | Description | Default value (if omitted) |
|---|---|---|
| x | X coordinate | 0 |
| y | Y coordinate | 0 |
| vx | Velocity vector X component | 0 |
| vy | Velocity vector Y component | 0 |
| code | Type of alien must be an integer in range [10-20] | 10 |
| level | Level of the alien, in range [0-X] where X depends on the alien type | 0 |
| points | The number of points you earn when you kill this alien | None |
| crystal_drop | The crystal amount to be dropped when this alien is killed | None |
| weapon_drop | The code of a collectible weapon to be dropped by this alien when killed | None |
Here is the list of supported codes:
| Code | Alien name |
|---|---|
| 10 | Chicken |
| 11 | Crab |
| 12 | Fortress |
| 13 | Caterpillar |
| 14 | Candlestick |
| 15 | Hirsute |
| 16 | Piranha |
| 17 | Pointu |
| 18 | Fork |
| 19 | Saucer |
| 20 | Final Boss |
A new Alien object is immediately added to game.aliens; however, it cannot be used before it has been assigned an id (natural number, a.k.a non-negative integer) by the server.
You can only have 300 alive aliens (including aliens generated by the game mode) at any time in your game
The server will respond with Too many aliens for each alien passing the limit
For each alien object in game.aliens, You have access to the same properties as the available ones when you add aliens, plus some additional properties:
| Option | Description |
|---|---|
| game | Points to the global game object |
| id | a unique identifier for the alien |
Once an alien is live and has an assigned id, you can set options to it. For example:
> game.aliens[0].set({x:0,y:0});
> █
Will move the first alien in the list to the center of the map
Accepted options when using alien.set:
| Option | Description | Server response error message (if improper) |
|---|---|---|
| x | X coordinate | Wrong coordinate |
| y | Y coordinate | Wrong coordinate |
| vx | Velocity vector X component | Wrong coordinate |
| vy | Velocity vector Y component | Wrong coordinate |
| shield | Shield | Wrong shield value |
| regen | Shield regen | Wrong regen value |
| damage | Laser damage | Wrong damage value |
| laser_speed | Laser speed | Wrong damage value |
| rate | Firing rate | Wrong rate value |
| kill | Set kill: (any "truthy" value, e.g: true) to destroy the alien |
No violation |
You can spawn collectible weapons in the playfield
You can also find a collectible with a specific id using game.findCollectible(id), which returns an object represents the matched collectible or null (if no collectibles are matching the provided id)
Here is an example:
> game.addCollectible({code:10,x:0,y:0});
> █
This will add a new collectible pack of rockets to coordinates (0;0)
Here is the list of supported codes:
(Note: Server will respond with Incorrect data when at least one input property value is improper)
| Code | Description |
|---|---|
| 10 | 4 rockets pack |
| 11 | 2 missiles pack |
| 12 | 1 torpedo |
| 20 | 8 light mines pack |
| 21 | 4 heavy mines pack |
| 40 | Mining pod |
| 41 | Attack pod |
| 42 | Defense pod |
| 90 | Energy refill |
| 91 | Shield refill |
You can only have 50 active collectibles (including collectibles generated by the game mode) at any time in your game
The server will respond with Too many Collectibles for each collectible passing the limit
For each collectible object in game.collectibles, You have access to the same properties as the available ones when you add collectibles, plus some additional properties:
| Option | Description |
|---|---|
| game | Points to the global game object |
| id | a unique identifier for the collectible |
You can access the list of moving asteroids through the array game.asteroids
You can also find an asteroid with a specific id using game.findAsteroid(id), which returns an object represents the matched asteroid or null (if no asteroids are matching the provided id)
To create an asteroid, use game.addAsteroid({ options }).
Here is the list of accepted options:
(Note: Server will respond with Incorrect data when at least one input property value is improper)
| Option | Description | Default value (if omitted) |
|---|---|---|
| x | X coordinate | 0 |
| y | Y coordinate | 0 |
| vx | Velocity vector X component | 0 |
| vy | Velocity vector Y component | 0 |
| size | Size of the asteroid in the range [1-100] | 30 |
A new Asteroid object is immediately added to game.asteroids ; however, it cannot be used before it has been assigned an id (natural number, a.k.a non-negative integer) by the server.
You can only have 300 alive asteroids (including moving asteroids generated by the game mode) at any time in your game
The server will respond with Too many asteroids for each asteroid passing the limit
For each asteroid object in game.asteroids, You have access to the same properties as the available ones when you add asteroids, plus some additional properties:
| Option | Description |
|---|---|
| game | Points to the global game object |
| id | a unique identifier for the asteroid |
Once an asteroid is live and has an assigned id, you can set options to it. For example:
> game.asteroids[0].set({x:0,y:0});
> █
Will move the first asteroid in the list to the center of the map
List of accepted options when using asteroid.set:
| Option | Description | Server response error message (if improper) |
|---|---|---|
| x | X coordinate | Wrong coordinate |
| y | Y coordinate | Wrong coordinate |
| vx | Velocity vector X component | Wrong coordinate |
| vy | Velocity vector Y component | Wrong coordinate |
| size | Asteroid size in the range [1-100] (note that changing asteroid size resets its life points) |
Incorrect size |
| kill | Set kill: (any "truthy" value, e.g: true) to destroy the asteroid |
No violation |
The mod can create custom, textured 3D objects and add them to the scenery using game.setObject method.
- A dimensional property included in this method is defined as an object with three fields represent 3 Axes in Coordinates
| Field | Represent for |
|---|---|
| x | X Axis |
| y | Y Axis |
| z | Z Axis |
| Option | Description |
|---|---|
| id | a unique identifier for this object instance (mandatory, allows changing the object afterwards) |
| type | the object type definition |
| position | coordinates for placing the object, dimensional property |
| scale | allows scaling the object, dimensional property |
| rotation | allows rotating the object, dimensional property |
| Option | Description | Default value |
|---|---|---|
| id | a unique identifier for this object type, mandatory | "undefined" or "null" depending on implementation |
| obj | a URL to the OBJ file | None |
| diffuse | a URL to a diffuse texture file (optional) | None |
| emissive | a URL to an emissive texture file (optional) | None |
| specular | a URL to a specularity texture file (optional) | None |
| bump | a URL to a bump texture map (optional) | None |
| emissiveColor | emissive color of the object, e.g. 0xFF0000 (for red) |
White if emissive is valid, Black otherwise |
| diffuseColor | diffuse color of the object, e.g. 0x00FF00 (for green) |
White if diffuse is valid, Black otherwise |
| specularColor | specular color of the object, e.g. 0x0000FF (for blue) |
White if specular is valid, Black otherwise |
| transparent | whether the object's texture has transparency or not | true |
| bumpScale | scale for bump mapping | 0.1 |
| shininess | the shininess of the specular map | 30 |
| physics | Object's physics | None |
All URLs included as property value must satisfy one of these conditions:
- It's a Data URL (
data:protocol) - The protocol must be
https(explicitly, not omitted) and the domain only matches one of these:
starblast.io(Official Starblast)starblast.data.neuronality.com(Neuronality's Starblast Data)github.com(GitHub)raw.githubusercontent.com(Raw GitHub Content)gitlab.com(GitLab)
If any URL-required fields mentioned above are present but don't satisfy these conditions, the whole object is rejected to be set on the players' clients.
Please note that GitHub and GitLab URLs can be easily converted into raw data URLs (such as changing /blob/ into /raw/ or appending ?raw=true at the end for GitHub URLs exclusively). Any URL using GitHub or GitLab domain should point to the raw file content and not the webpage version of the file itself.
Note: We recommend not to use this property as it usually doesn't work as expected
| Option | Description |
|---|---|
| mass | Object mass, same as the specs.ship.mass property in Ship Editor TutorialNote: If the mass is too small (<100), ships can go through the object |
| shape | Object's shape, used for creating hitbox You can omit this property to set default shape generated from the object itself or provide an array for your custom shape |
For example:
var cube = {
id: "cube",
obj: "https://raw.githubusercontent.com/pmgl/starblast-modding/master/objects/cube/cube.obj",
diffuse: "https://raw.githubusercontent.com/pmgl/starblast-modding/master/objects/cube/diffuse.jpg"
} ;
game.setObject({
id: "cube",
type: cube,
position: {x:0,y:0,z:0},
rotation: {x:0,y:0,z:0},
scale: {x:1,y:1,z:1}
}) ;Game property game.objects stores all active 3D Objects maintained by the mod
You shouldn't modify this property to keep the mod running smoothly
Use game.setObject again with the same object instance ID.
Note: Object type's properties can not be changed once set. You may need to define a new object type instance with different ID and set the object you wish to update with the new object type ID.
game.removeObject(id) removes the object with given id. You can omit the id parameter, which will remove all custom objects in the scene.
Working example, adding cube objects to the scenery: https://github.com/pmgl/starblast-modding/blob/master/examples/adding_cube.js
Once the mod starts running, all detailed options will be passed into the game.options object
This includes all properties defined in this.options, plus some extended fields listed below (except if they are not defined):
| Field | Description |
|---|---|
| bouncing_lasers | if bouncing lasers is enabled or not |
| max_tier_lives | number of lives when the player reaches ships with the highest level (defined in max_level option) |
| Field | Description |
|---|---|
| teams | an array represent teams' most basic info each item in the array contains: base_name: name of the basefaction: faction namehue: team hue |
| crystal_capacity | an array presenting the capacity of the stations in the increasing level order |
| deposit_shield spawning_shield structure_shield |
an array presenting the the stations' deposit/spawning/structure modules (depots/spawn ports/small structures) shield in the increasing level order |
| deposit_regen spawning_regen structure_regen |
an array presenting the the stations' depots/spawn ports/small structures regeneration in the increasing level order |
You can assign properties into some game entities or objects as side notes/indicators
Simply just call out their custom property (which is always an object) and assign properties to it.
gameobject- all ships
- all aliens
- all collectibles
- all asteroids
game.custom.hasMod = true // game object
game.ships[0].custom.userScore = 6712 // ship entity
game.aliens[0].custom = {created: true, rating: "10stars"} // alien entity
game.asteroids[0].custom = {init: true} // asteroid entityYou can use game.setCustomMap(<map pattern>) to set custom map while the game is running
where <map pattern> has the same format as the custom map in this.options
Use game.setOpen(true/false) to lock/unlock the mod to be visible to players (only for Modding Space mods)
There is also game boolean properties game.is_open is used to determine if the mod is open or not
In most cases, you're getting a black screen after loading your mod due to a bad ship tree.
Follow these rules to avoid it:
- Your ship tree must have a ship with type/code 101.
- If your ship tree has level 2 ships, then it should have level 1 ships too.
- Either models should go in the right order without gaps: 1, 2, 3 etc (not 1, 6, 17) or control all ship tree routes by
nextparameter in ship codes (but keep correct order for unreachable ships). - You can't have possibly infinite ship tree routes, made by
nextparameters - all routes should end at some ship, there shouldn't be able to come back to some ship again.
Sometimes, some unexpected problems can crash the mod, but it only disconnects from the modding side, or so-called "controller" side, the game itself will continue running without control from your modding client until it meets the closing requirements (or even in some serious occasions, game developers - like PMGL - need to close it by themselves).
Here are some reasons which can lead to mod crashing:
- Closing/Reloading the modding tab/window without stopping the mod first (Most common one)
- Very unstable internet connection
- Server resolve error (which will automatically disconnect the controller by itself)
- Browser tab hangs/crashes (careful of infinite while/for loops)
Also keep in mind that you can't reconnect to your previously crashed server, even if it's still running.
You will only need to set max_players to a value higher or equal to 200, and root_mode as "team"
- Modding Tutorial - Wiki version
- Ship Editor Tutorial
- How to add ship to the mod - by InterdictorSD
- Modding Live #2 by PMGL
- General modding tutorial by Wolfan
- Mod Editor
- Ship Editor
- Map Editor (by community)