Room scripts
Host a RosikBall room run by your own code.
Anyone can run a room with a script: it welcomes players, picks the teams, starts and stops games, answers
!commands, keeps statistics, records replays — whatever you write. The room runs where your script runs:
in a browser tab on your computer. It is free and needs no account.
- Quick start: a room in a browser tab
- Creating the room
- Every command at a glance
- Players
- Events
- Actions
- Reading the room
- The field: goals, discs, objects, a scoreboard
- Balls
- Light
- Bots
- Captains
- AFK players
- Admins
- Replays
- Scripted maps
- Familiar calls: discs, flags, stadiums, units
- Examples
- The sandbox and its limits
- What a script cannot do
Quick start: a room in a browser tab
- Open rosikball.com/?headless=1 — a headless page: it hosts a room but has no player of its own and draws nothing. It waits for your script.
- Open the browser's console (F12 → Console).
- Paste your script and press Enter (the first time, the browser asks you to type
allow pastingbefore it lets you paste into the console). For instance:
const room = RosikRoom.create({ roomName: 'My first room', maxPlayers: 10, public: true });
room.onRoomLink = (link, code) => console.log('Room open:', code, link);
room.onPlayerJoin = (p) => {
room.sendAnnouncement(`Welcome, ${p.name}!`, p.id, { color: '#ffd166', bold: true });
// the first two players get a team each, then the game starts
const red = room.getPlayerList().filter(x => x.team === 'red').length;
const blue = room.getPlayerList().filter(x => x.team === 'blue').length;
if (red === 0) room.setPlayerTeam(p.id, 'red');
else if (blue === 0) { room.setPlayerTeam(p.id, 'blue'); room.startGame(); }
};
The room appears on the room list (or not, with public: false: then share its code or invite link).
Keep the tab open: closing it closes the room. A headless page keeps running in a background tab.
You can also run a script on the normal game page (you keep your own player and host with it).
Creating the room
const room = RosikRoom.create({
roomName: 'Friday 4v4', // shown on the room list
password: '', // '' = none
maxPlayers: 8, // 2–24
public: true, // on the room list (false: code / invite link only)
field: 'classic', // 'classic' | 'easy' | 'small' | 'big' | 'rounded' | 'bigeasy' | 'bigrounded' | 'futsal' | 'futsalbig' | 'sixman' | 'basketball' | 'night' | 'floodlights' | 'skilltraining'
map: null, // or a custom map (a .rbmap's object): played instead of the field
timeLimit: 3, // minutes, 0 = none
scoreLimit: 3, // goals, 0 = none
teamsLock: false, // true: only admins (and the script) move players
discord: 'discord.gg/abc123', // your community: a Discord invite, shown in the room with the Discord logo
platforms: 'all', // who may join: 'all' (the default here), 'web' (players on a computer), 'app' (the RosikBall app)
league: false, // true: a league match room — every finished match published under a match code (League matches)
admins: [] // account ids (player.account) who are admin as soon as they join
});
A scripted room starts stopped: your script starts the games (room.startGame()). One room per page.
Every command at a glance
Everything a script can call or hear, grouped; each links to where it is explained. id is a player's id,
team is 'red', 'blue' or (for players) 'spec'. The same API works in a
browser tab and in a map's sandbox (where actions are rationed).
| Group | Commands |
|---|---|
| The room | RosikRoom.create(config) |
| Reading | getPlayerList() getPlayer(id) getScores()
getBallPosition(id) isGameRunning() getTeamCaptain(team) getRoomCode()
getRoomLink() getMap() getScoreboard() reclaimKey |
| Players | setPlayerTeam(id, team) setPlayerAdmin(id, on)
kickPlayer(id, reason, ban) clearBans() clearBan(id) reorderPlayers(ids, moveToTop) mutePlayer(id, minutes) unmutePlayer(id)
setPlayerAfk(id, on) setTeamCaptain(team, id) setRoomAdmins(accountIds)
setTeamsLock(on) — and suspendPlayer(id, seconds) getSuspensions() |
| Card badges | setPlayerBadges(id, badges) getPlayerBadges(id) |
| Games | startGame() stopGame() pauseGame(on, by?)
setTimeLimit(minutes) setScoreLimit(goals) setField(name) setMap(map)
setCustomStadium(text) setDefaultStadium(name) setKickRateLimit(min, rate, burst) getKickRateLimit() |
| Room settings | setRoomName(name) setPublic(on) setPassword(text)
setMaxPlayers(n) setDiscord(link) setPlatforms(rule) getPlatforms() setLeague(on) getLeague() |
| Chat, sounds | sendAnnouncement(text, toId, style) sendChat(text, toId) playSound(name, to) |
| Discs, flags | getDiscCount() getDiscProperties(index) setDiscProperties(index, props)
setTeamColors(team, angle, textColor, colors) CollisionFlags InputFlags |
| The field | getGoals() getZones() getPlayerDiscProperties(id)
setPlayerDiscProperties(id, props) getBallProperties(id) setBallProperties(props, id)
setObject(id, object) removeObject(id) clearObjects() getObjects()
setScoreboard(entries) setMobileScoreboard(board, id) setScoreboardPopup(lines) setRoomNotice(notice) setGoalMessages(on) setPlayerAvatar(id, avatar)
setPlayerColor(id, color) setPlayerLook(id, look) getPlayerLook(id) setTeamLook(team, look)
getTeamLook(team) setKickoffTouch(seconds) getKickoffTouch() setNoWaller(on) getNoWaller() setGoalColor(goal, color) setGoalTeam(goal, team) setPlayerAfkPaused(id, on) setPlayerCard(id, lines) setPlayerSpawn(id, point) scoreGoal(team, scorerId) |
| Balls | getBalls() setBall(id, props) removeBall(id)
clearBalls() — and getBallProperties(id) / setBallProperties(props, id) |
| Game timers | setTimer(id, seconds, {repeat, paused}) clearTimer(id)
clearTimers() getTimers() |
| HUD widgets | setHud(id, widget) clearHud() getHud() |
| Areas and points | getAreas() getPoints() isInArea(area, point) |
| Barriers | setBarrier(id, barrier) clearBarriers() getBarriers() |
| Markers | setMarker(id, marker) clearMarkers() getMarkers() |
| Player effects | setPlayerEffect(id, name, effect) getPlayerEffects(id) |
| Light | getLights() getGlobalLight() setLight(ids, props, seconds)
setGlobalLight(props, seconds) resetLights(seconds) — and setObject with a light |
| Bots | addBot(team, opts?) removeBot(id) setBotTarget(id, point)
setBotAim(id, point) setBotHints(hints) |
| Replays | startRecording() await stopRecording() saveReplay(bytes, name) |
| Scripted maps | setMapScripts(on) getMapScript() |
| Events | onRoomLink onPlayerJoin onPlayerLeave onPlayerKicked
onPlayerChat onPlayerTeamChange onPlayerAdminChange onPlayerAfkChange
onTeamsLockChange onLeagueChange onLeagueMatchStart onMatchPublished onGameStart onGameStop onGamePause onGameUnpause
onTeamGoal onPlayerBallKick onPlayerBallTouch onTeamVictory
onPositionsReset onGameTick onPlayerEnergyPad onTimer onBallArea
onPlayerArea onPlayerButton onPlayerInput onPlayerActivity onPlayerContact
onPlayerSuspensionEnd onStadiumChange onKickRateLimitSet onPlayerWallJump |
An action returns true when it is queued (it applies at the next tick), false when it cannot be (a
player who is not in the room, a room that has closed, a sandbox's limit reached); a wrong argument throws, saying why.
Players
Every player your script gets is a snapshot (read it again for fresh values):
{ id, name, team, // team: 'red' | 'blue' | 'spec'
avatar, admin, bot,
color, // the disc's own colour ('#rrggbb', setPlayerColor), null: the team's
look, // the disc's own look ({pattern, color, color2, avatar, avatarBorder}, setPlayerLook), null: the team's
card, // the popup on their card in the room menu (setPlayerCard), null: none
badges, // the badges under their name on that card (setPlayerBadges), null: none
suspended, // {team, seconds} while suspended (suspendPlayer): the team they go back to, game seconds left; else null
verified, // logged in: the name is their account's nickname
account, // their account's id (checked by our server) — the identity to trust; null for guests
auth, // a key of their browser: the same in every room, guests too — no server checks it (account is)
conn, // an opaque id of their network: two players with the same one share a connection — never their address
input, // the keys they hold now (room.InputFlags, | together: up 1, down 2, left 4, right 8, kick 16, jump 32, use 64)
country, // two letters, from their connection (never chosen by the player)
platform, // where they play from: 'web', 'app-android' or 'app-ios' (from their connection); null for a bot
afk, // away from the keyboard (see AFK players)
captain, // 'red' | 'blue' while they pick their team, else null
roomAdmin, // one of the admins named with admins / setRoomAdmins
position } // {x, y, z} on the pitch, null for spectators
Names can be anything a player types: show them as text, never as HTML.
Events
Set the handlers you need: room.onPlayerJoin = (player) => { … }. A handler that throws is logged and
skipped; the room keeps running. byPlayer is the player who did it — a joined admin, a captain, a player moving
themselves — or null when the host, a script or the game itself did. A handler the game does not know yet (a script
written for a newer version than the page) is kept and never called, with one warning in the console: reload the page to have it.
| Handler | When |
|---|---|
onRoomLink(link, code) | the room is open (its invite link and code) |
onPlayerJoin(player) | someone joined (as a spectator) |
onPlayerLeave(player, reason) | left, timed out, kicked or banned |
onPlayerKicked(player, reason, ban, byPlayer) | before the leave |
onPlayerChat(player, text, {scope, to}) | a message — return false to drop it (for !commands). scope: 'all', 'team' (only the sender's team reads it) or 'private' (only to, a player, and the sender) |
onPlayerTeamChange(player, byPlayer) | moved to a team or the spectators; byPlayer is the captain who picked them, else null |
onPlayerAdminChange(player, byPlayer) | admin given or taken |
onPlayerAfkChange(player, afk, by) | away or back — by: 'self' (typed !afk), 'idle', 'back' (pressed a key), 'script' |
onTeamsLockChange(locked, byPlayer) | the teams were locked or unlocked |
onLeagueChange(on, byPlayer) | League match was switched on or off (League matches) |
onLeagueMatchStart(code) | a league match room's match began: its match code, readable live by it |
onMatchPublished(code, report) | a league match room's match was published: its match code and the report |
onGameStart(byPlayer) / onGameStop(byPlayer) | a game started / was stopped |
onGamePause(byPlayer) / onGameUnpause(byPlayer) | paused / play resumed (after the countdown; at once after a freeze without one) |
onStadiumChange(name, byPlayer) | the field changed (a built-in or a map): its name |
onKickRateLimitSet(min, rate, burst, byPlayer) | the kick rate limit changed (setKickRateLimit, an admin's /kick_ratelimit) |
onTeamGoal(team, scorer, assist, ownGoal, where) | a goal (a shot on target that a defender deflects in is the shooter's);
where says which goal it went into: {goal, zone, defendedBy, x, y, z} — goal = its index in
room.getGoals() (zone: a goal zone's, in room.getZones()), x, y, z the ball and
ball its id (a room may have several balls) |
onPlayerBallKick(player, ball) | a kick — ball as getBalls() gives it (one kick reaches every ball in range: one event each) |
onPlayerBallTouch(player, ball) | a disc begins touching a ball — a kick, a block or a bump (who hit it last) |
onPlayerEnergyPad(player, {pad, amount}) | a disc took an energy pad (maps with energy): pad its index among the map's energy zones, amount the points it gives |
onPlayerWallJump(player) | a disc in the air jumped off a wall (a map whose walls discs jump off, its wall jump on) |
onTeamVictory({winner, red, blue}) | a game was won |
onPositionsReset() | after a goal, back to the kickoff |
onTimer(id) | a game timer of yours ran out |
onBallArea(ball, area, inside, at) | a ball's centre crossed a map area's edge — inside: it came
in (false: it went out); at: {x, y, z, edge, lastTouch} — where it crossed, which side of the box
('x+' 'x-' 'z+' 'z-' in the box's own frame, 'top' / 'bottom',
'side' for a cylinder) and the player who touched the ball last |
onPlayerArea(player, area, inside, at) | a disc's centre crossed an area's edge |
onPlayerButton(player, button, down, held) | a player pressed or let go of 'kick', 'jump' or 'use';
on a release, held = how long, in seconds of game time (a power charged by holding a key) |
onPlayerInput(player, prevInput) | any of a player's keys changed: player.input the keys now, prevInput before (room.InputFlags) |
onPlayerActivity(player) | a player on the pitch did something (a key changed): a sign of life |
onPlayerContact(a, b, {speed}) | two discs began touching; speed: how fast they met (m/s) — a tackle, a foul |
onPlayerSuspensionEnd(player, back) | a suspension is over: back true = put on their
team again; false = they stay a spectator (their team has its players again, or the game stopped) |
onGameTick(tick) | every gameplay tick, 120 per second — keep it light: in a map's sandbox the whole room is copied for it each time; prefer timers and the events above |
Actions
Actions are the room host's own: they apply at the next tick, with the same rules as the room menu (the field and the limits change only while no game runs).
room.setPlayerTeam(id, 'red') room.setPlayerAdmin(id, true)
room.kickPlayer(id, 'reason', ban) room.clearBans()
room.mutePlayer(id, minutes | null) room.unmutePlayer(id)
room.startGame() room.stopGame() room.pauseGame(true | false [, by])
room.pauseGame(true, null, { seconds: 2, countdown: false, banner: 'OFFSIDE', sub: 'free kick Blue', color: '#ffd23f' })
// a freeze: ends by itself (no 3-2-1 with countdown: false), a banner of its own
// ('' = none), no chat line, the field stays in colour
room.setTimeLimit(minutes) room.setScoreLimit(goals) room.setField('big')
room.setMap(mapObjectOrText) // a custom map (.rbmap): checked at once (throws why); its limits come with it
room.setField('custom') // back to the room's custom map (the last setMap, or create's map)
room.setTeamsLock(true) room.setPassword('secret' | '')
room.setRoomName('Friday 4v4') room.setPublic(true | false) room.setMaxPlayers(10)
room.setPlatforms('web' | 'app' | 'all') // who may join: players on a computer, on the RosikBall app, or both — applied
// while no game runs; nobody already in leaves. getPlatforms() reads it
room.setDiscord('discord.gg/abc123' | '')
room.setTeamCaptain('red', id | null) // see Captains
room.setPlayerAfk(id, true | false) // see AFK players
room.setAfkSeconds(60 | 0 | null) // the room's AFK time (0: never by idling; null: the game's 30 s)
room.setRoomAdmins([accountId, …]) // see Admins
room.addBot('blue') room.removeBot(id)
room.addBot('red', { position: 'DM', level: 4, brain: 'light' }) // each optional
room.setBotTarget(id, { x, z } | null) room.setBotAim(id, { x, z } | null) // see Bots
room.setBotHints({ offside: 4, outOfPlay: true } | null) // see Bots
room.sendAnnouncement(text, toId = null, { color: '#ffd166', bold: true })
room.sendAnnouncement(text, toId = null, { type: 'warning' })
room.playSound('whistle', to = null) // 'whistle' 'whistle-long' 'whistle-double' 'horn'; to: null, 'red' / 'blue', a player's id
room.playSound('horn', null, { volume: 0.6, pitch: 1.3, at: { x: 30, z: 0 } }) // softer, higher, from a spot on the field
room.startRecording() const bytes = await room.stopRecording(); room.saveReplay(bytes, 'name')
Announcements are system lines in the chat, to everyone (toId = null) or one player. With a
type — 'info', 'success', 'warning' or 'error' — the
announcement also pops up in the bottom-right corner for a few seconds, in that kind's colour;
line: false makes it a popup only. Admins can send the same from the chat:
/announce warning the room restarts in 5 minutes, or to one player with @name:
/announce success @Ana you are captain. A player about to be set AFK gets a warning popup
from the game itself, three seconds before.
playSound plays one of the game's own sounds on the players' screens — a referee's short whistle, a long one, two
short ones, a stadium horn — for everyone, a team or one player. Its options: volume (0–2, 1 as made), pitch
(0.5–2: 2 is an octave higher) and at {x, z}, a spot on the field — each player hears it louder the nearer it is to their
disc (or, watching, to what their camera shows) and from that side, never silent. It is only a sound (nothing in the game changes;
players with the sound off hear nothing) and recordings do not keep it.
Reading the room
room.getPlayerList() | everyone in the room (the headless page itself is not a player) |
room.getPlayer(id) | one player, or null |
room.getScores() | {red, blue, time, timeLimit, scoreLimit, overtime, phase, kickoffTeam} (kickoffTeam: the team whose kickoff it is, or the next one) |
room.getBallPosition() | {x, y, z} |
room.isGameRunning() | a game is on (playing, paused or between goals) |
room.getTeamCaptain(team) | the team's captain's id, or null |
room.getRoomCode() / room.getRoomLink() | the code and the invite link |
room.getMap() | {field, name, author}: the field in use, a built-in id or 'custom' |
room.getScoreboard() | your scoreboard as setScoreboard left it, or null (the score shows) |
room.reclaimKey | the key that gets the room's code back after a restart |
The field's own readings — getGoals, getZones, getPlayerDiscProperties,
getBallProperties, getObjects — are in the next section.
The field: goals, discs, objects, a scoreboard
The room plays Red against Blue. Anything else — a goal for each player, lives, rounds, more teams —
is your script's: it can read the field, move discs, put objects of its own on the pitch and show its own scoreboard.
Coordinates are metres: x along the field, z across it, y up.
room.getGoals() | the field's goals, in order: {index, team, a, b, middle, normal, width, height, depth}
— team defends it, a / b its posts and middle as {x, z},
normal points into the net |
room.getZones() | the field's zones (a basket's goal zone…): {index, effect, team, from, x, z, bottom, top} |
room.getPlayerDiscProperties(id) | {x, y, z, xspeed, yspeed, zspeed, radius}, or null for a spectator |
room.setPlayerDiscProperties(id, props) | moves the disc: any of x, y, z, xspeed, yspeed, zspeed
(a teleport — no goal is crossed on the way) |
room.getBallProperties() / room.setBallProperties(props) | the same for the ball |
room.setObject(id, object) | puts a 3D object of your own on the field — or changes it, by its id
(letters, digits, _ - . :). Everyone sees it, it stops what it stops, replays keep it. |
room.removeObject(id) / room.clearObjects() / room.getObjects() | (a field change removes them all; at most 64) |
room.setScoreboard(entries) | your own scoreboard in place of "Red 0 : 0 Blue", on every player's screen:
[{text, color, faded, pips}] (a dot of the colour; faded = greyed and struck through; pips: {count, max, color}
= circles — lives, rounds —, count filled and the rest hollow, 12 at most; an entry may be pips alone) or plain
strings; null brings the score back. |
room.setMobileScoreboard(board, id) | what phones show in their narrow score chip, instead of the
scoreboard above: entries (as setScoreboard's), 'score' (the usual Red : Blue score) or null
(the scoreboard above, shrunk to fit). With a player's id: that player's own phone board — their own lives only, say
—; null clears it. A tap on the chip shows setScoreboardPopup's lines, so put everything there too. |
room.setScoreboardPopup(lines) | what hovering the score panel shows, on every player's screen, instead of
the match's goals ("1-0 Ana (Bob)" means nothing to a game you score your own way): plain strings or
{text, color: '#rrggbb', bold}, up to 16 lines of 80 characters. Call it again when the values change (an open popup
updates); null: the goals again. |
room.setRoomNotice(notice) | a line at the top of the room menu — the teams' view everyone sees between
games —, for everyone: {text, sub, color: '#rrggbb', seconds} (sub a smaller line under it, up to 200
characters; seconds a countdown shown after the words, running on every screen by itself, 15 minutes at most), or a
string for the words alone; null: none. E.g. {text: 'Waiting for Bob', sub: 'The game starts as soon as Bob is here',
seconds: 45} while your game waits for a player. |
room.setPlayerSpawn(id, {x, z}) | where a player starts every kickoff — the reset after a goal and a game's start —
instead of their team's spot: the reset puts them there itself, so nothing moves after it (a teleport in
onPositionsReset shows them on their team's spot first). Set during the reset's short freeze (in
onGameStart) it applies at once. null: the team's spot again; a field change, the player leaving or your
script stopping drops it. |
room.setGoalMessages(false) | turns off the game's own goal texts — the "GOAL! RED scores (Ana)" banner and the
chat's goal line — for a script that announces its goals or points its own way; true turns them back on.
They are on unless your script says so. |
room.setPlayerAvatar(id, avatar) | a player's avatar (two characters at most: letters, a number, an emoji) |
room.setPlayerCard(id, lines) | a popup on the player's card in the room menu (Esc): whoever
hovers the card sees the player's name and your lines — plain strings or {text, color: '#rrggbb', bold}, up to 8
lines of 80 characters, shown as text. Call it again whenever the values change: every player's menu updates at once, an
open popup too. Your lines come on top of what a registered player's card always shows — when they joined RosikBall and
the positions they play —, with a divider between. null: your lines go (a guest's card then shows nothing
on hover). |
room.setPlayerColor(id, '#rrggbb') | a player's disc in a colour of its own instead of their team's, on every screen and in
replays (a free-for-all, a marked player…); null: the team's colour again |
room.setPlayerLook(id, {pattern, color, color2, avatar, avatarBorder}) | a player's disc in a look of its own: a pattern in one or two
colours, the avatar's colour and its border's. Patterns: plain, ring (an outer and an inner colour), stripes (a striped
shirt), hoops, halves, sash, quarters, dots, star. Colours are
'#rrggbb': color the main one (left out: the team's), color2 the second (patterns that have one; left out:
white), avatar the avatar's (left out: white), avatarBorder the outline round the avatar's letters (left out: the
usual dark one). The pattern runs from the top over the disc's rounded edge and down its side. On every screen and in replays; null: the team's look again.
room.getPlayerLook(id) reads it. |
room.setTeamLook('red' | 'blue', look) | every disc of a team in a look (as above) over the map's (a map sets its teams'
looks in the editor: Look → Discs); a player's own look still wins. null: the map's look again.
room.getTeamLook(team) reads what the team wears. |
room.setThreeMen(true | false | null)room.getThreeMen() | the 3 men rule, on or off whatever the map
or the room's admins say (null: theirs again). A team of exactly four players (whatever the other team's size) defends with three:
while the ball is in play, only three of its players may be in their own half — the others meet the halfway line as a wall (a red one, on their
own screen) and come back only once a teammate steps up. With all four back (the kickoff puts them there), the one nearest halfway can't go deeper
and is walked out over it. getThreeMen() says whether it is on now. |
room.setKickoffTouch(seconds | true | false | null)room.getKickoffTouch() | "No direct kickoff goals":
in the first seconds of play after a kickoff (a pause does not count), a goal for the team that kicked off counts only once the other
team has touched the ball — otherwise it is no goal, every screen says NO GOAL and the other team kicks off. true: 3 seconds;
0 / false: off whatever the map or the room's admins say; null: theirs again (Futsal has it on).
getKickoffTouch() gives its seconds now (0: off). |
room.setNoWaller(true | false | null)room.getNoWaller() | No Waller: goals off the wall do not count.
A goal whose ball hit one of the map's walls after the last player touched it is no goal (an own goal still counts), every screen says NO GOAL and the
team that defended kicks off. A touch after the wall (a pass off the wall, then the shot) and the goal counts; posts, the crossbar, the net, the
floor and the ceiling are not walls. false: off whatever the map or the room's admins say; null: theirs again.
getNoWaller() says whether it is on now. |
room.setEnergyRules(rules | false | null)room.getEnergyRules()room.getPlayerEnergy(id)room.setPlayerEnergy(id, points) | energy:
every player gets a meter that the map's energy pads fill and that holding Use (C, a controller's RT) spends on an effect —
Rocket Ball's boost. rules = {label, max, start, drain, regen, color, effects: {speed, accel, jump, kick, size}}
(each effect a multiplier while it is used: {speed: 1.6} is Rocket League's boost, {size: 2} a disc that grows,
{jump: 2} a super jump); on any map, whatever it says. false: no energy, even on a map that has it; null:
the map's again. getPlayerEnergy / setPlayerEnergy read and set a player's points (a reward, a refill); without
energy they give null / false. The pads are map zones (the editor's ⬚ Zone tool, effect "energy pad"):
onPlayerEnergyPad says when one is taken. |
room.setGoalColor(goal, '#rrggbb') | a goal's frame — its posts and crossbar — in a colour of its own, on every screen and in
replays: goal is its index in getGoals() (a free-for-all paints each player's goal in their colour);
null: the colour of the team that defends it again. A field change drops it. |
room.setGoalTeam(goal, 'red' | 'blue') | who defends a goal for now: a goal there counts for the other team, as
any goal does — the score, own goals, bots — and its frame takes that team's colour. null: its map's team again (getGoals()
gives team, who defends it now, and mapTeam). A penalty shoot-out at one goal gives it to the keeper's team before each
kick. A field change drops it. |
room.scoreGoal(team, scorerId) | a goal for 'red' or 'blue' as if the ball had gone in — the score,
the kickoff, the limits and the recap as for any goal (scorerId or null): points your script decides
(ping pong, targets, a field without goals). Only while a game is on; onTeamGoal hears it with where.script. |
A field may have no goals at all (a room script scores with scoreGoal), and a field's physics may make the discs
float at a height (the editor's Physics tab, "Players float this high": they glide at that height, steer as on the ground and
still jump — the map's Jumping rule).
An object is a map editor object: {shape: 'box' | 'cylinder' | 'sphere' | 'ring' | 'net', at: [x, z], y, w, d, h,
yaw, tilt, stops: 'all' | 'ball' | 'players' | 'none', bounce, opacity, color: '#rrggbb', name, light} — y its middle's
height; a box is w along × h × d, turned by yaw degrees; opacity: 0
is not drawn; light makes it a light source (see Light). A wall across a
goal's mouth, from getGoals():
const g = room.getGoals()[2];
room.setObject('shut-2', {
shape: 'box', at: [g.middle.x + g.normal.x * 0.2, g.middle.z + g.normal.z * 0.2], y: (g.height + 0.3) / 2,
w: g.width + 0.5, d: 0.3, h: g.height + 0.3, yaw: Math.atan2(-(g.b.z - g.a.z), g.b.x - g.a.x) * 180 / Math.PI,
stops: 'all', color: '#5a6270', opacity: 0.75
});
Balls
A room may have several balls. A map can have up to 10 (the map editor's ● Ball tool) and a script adds as many as it
likes (setBall; the network carries up to 255). Each ball has its own spot — where it starts, and where it
goes back at every kickoff — and may have its own physics and look. Every ball plays like the ball: a kick reaches every
ball in range, any ball scores in any goal (the goal event says which), the bots play the ball nearest to them, replays keep
them all. The map's balls are "map:0" (the first — the ball of everything that knows only one, like
getBallProperties() without an id), "map:1"…; a script names its own (letters, digits,
_ - . :).
| Call | What it does |
|---|---|
getBalls() | every ball, in the room's order: {id, x, y, z, xspeed, yspeed, zspeed, radius, mass, damping,
bounce, playerBounce, maxSpeed, gravity, pattern, texture, color, color2, spawn: {x, y, z}, map, lastTouch} |
getBallProperties(id)getBallPosition(id) | one ball the same way (no id: the first), or null |
setBall(id, props) | adds a ball of the script's own — it needs x and z, its spot — or changes one,
one of the map's too ("map:1"). Props: x, z, y (where it starts: on the floor unless y says higher),
radius 0.12–1.2 m, mass 0.1–10, damping 0–0.95 (drag per second), bounce 0–1.2,
playerBounce 0–1.2, maxSpeed 5–60 m/s, gravity 0–40 m/s², kick 0.3–3 (the speed a kick
gives it, scaled: a light or a heavy ball, a pass streak's boost), curve 0–5 (the map's kick curve on it, scaled),
lob 0.5–3 (a lofted kick's reach: its speed along the floor × this at a full lob, as high — a longer, flatter lob; 1 = as
any kick), pattern
('plain' 'football' 'stripes' 'halves' 'segments' 'dots'
'ring'), texture — its material ('smooth' 'matte' 'leather' 'pebbled'
'dimpled' 'felt' 'rubber'; the game's ball is leather) —, color, color2
('#rrggbb'). What a ball leaves out is the map's ball.
A new ball appears on its spot; a field change removes the script's balls. |
setBallProperties(props, id) | moves a ball now — x, y, z, xspeed, yspeed, zspeed (a teleport, no
goal on the way) — and takes setBall's keys too ({radius: 0.6, color: '#ff0000'}), and for the ball as it is now:
hold: true (it stays on its spot like a post and only a kick moves it — a set piece's ball; holdFor: 'red': only
Red's kick; a kick or a kickoff frees it; hold: false: free now) and push: {x, z} (m/s² along the floor, fading
over pushFade seconds: a wind, a magnet, a stronger curve) |
removeBall(id) | takes one of the script's own balls away (the map's stay: change them instead) |
clearBalls() | takes away every ball the script added and gives the map's balls back their own settings |
// two more balls at every kickoff: a football and a slow, floaty balloon
room.onPositionsReset = () => {
room.setBall('extra', { x: -4, z: 3, pattern: 'football', color: '#ffd166' });
room.setBall('balloon', { x: 4, z: -3, radius: 0.6, mass: 0.3, gravity: 3, damping: 0.8, pattern: 'dots', color: '#ff6b9a' });
};
room.onTeamGoal = (team, scorer, assist, ownGoal, where) => {
if (where.ball === 'balloon') room.sendAnnouncement('The balloon went in! 🎈');
};
room.onPlayerBallKick = (player, ball) => {
if (ball.id === 'extra') room.setBallProperties({ color: player.team === 'red' ? '#e64c40' : '#3d7aeb' }, 'extra');
};
The built-in 6 Players Skill Training field shows what a map alone can do: six closed pieces, a ball and a spawn spot in each, made in the map editor without a line of script.
A map's physics may make every kick bend against the kicker's run (the editor's Physics tab: "Kick curve" and "Curve fades
in"): Real Soccer's. In the air that curve only turns the ball — it never brakes a lob (a script's push
pushes in the air too).
Game timers
Timers that count the game's own ticks: a pause stops them, and every run of the room gives the same result — unlike
setTimeout, which keeps running through a pause. When one runs out, onTimer(id) hears it.
room.setTimer('restart', 14) // onTimer('restart') after 14 s of game time
room.setTimer('blink', 0.2, { repeat: true }) // again every 0.2 s until cleared
room.setTimer('review', 2, { paused: true }) // counts through pauses and freezes too
room.clearTimer('restart') room.clearTimers() room.getTimers() // [{id, seconds}]: the seconds left
The same id again starts it over; 100 at once at most.
HUD widgets
Text, a timer, a bar or a row of dots on the players' screens — at a place on the screen (at) or following a
disc, a ball or a spot on the field (attach), for everyone, one team or one player (to). A widget with a
time runs by itself on every screen on the game's clock (it stops while the game stands still), so it costs no
message while it runs; steps change its text or colour as it goes.
// a goal kick's countdown: five dots over the keeper, lit one by one, yellow to red, blinking at the end
room.setHud('gk', { type: 'dots', attach: { player: id }, count: 5, time: { seconds: 14 }, color: '#ffd23f', color2: '#ff3b2f',
empty: '#111111', background: 'none', size: 'l', blink: 11.5 });
// a timer under the score
room.setHud('throw', { type: 'timer', at: 'top', text: 'Throw-in', time: { seconds: 14 }, format: 'ss', color: '#8fb8ff' });
// what holding kick would do, over the player's disc, only on their screen: 👟, then ⚡, then nothing
room.setHud('pw', { type: 'text', attach: { player: id }, to: id, background: 'none', size: 'l',
steps: [{ at: 0.5, text: '👟' }, { at: 1.2, text: '⚡' }, { at: 2, text: '' }] });
// an icon of your own over a disc (drawn by the game from SVG path data, as on the card badges): a yellow card, 3 s
room.setHud('card', { type: 'text', attach: { player: id }, background: 'none', size: 'xl', seconds: 3,
icon: { paths: [{ d: 'M8.6 2.4l8.4 1.5c.8.1 1.3.9 1.2 1.7l-2.5 14.3c-.1.8-.9 1.3-1.7 1.2L5.6 19.6c-.8-.1-1.3-.9-1.2-1.7L6.9 3.6c.1-.8.9-1.3 1.7-1.2z',
fill: '#ffd23f', stroke: '#1a1a1a', width: 0.9 }] } });
room.setHud('gk', null) room.clearHud() room.getHud() // [{id, …, up: seconds since it was set}]
| Key | What it is |
|---|---|
type | 'text' 'timer' 'bar' 'dots' |
at / attach | a place on the screen — 'top' 'top-left' 'top-right' 'left'
'center' 'right' 'bottom' 'bottom-left' 'bottom-right' — or {player: id},
{ball: id}, {point: {x, y, z}} (above it); dx / dy move it (px) |
to | null (everyone), 'red', 'blue' or a player's id: only they are sent it |
icon | an icon of your own before its text (alone: the whole widget) — as a card badge's: {view, paths: [{d, fill, stroke,
width}]}, SVG path data the game draws (never markup); a path without a fill takes the widget's colour |
text, value, count | its words; a bar's or the dots' fill 0–1 without a time; how many dots (≤ 12) |
time, format | {seconds, mode: 'down' | 'up'}; a timer's 'ss' 'mm:ss' 's.t' |
steps | [{at, text, color}]: from at seconds on, that text / colour |
color, color2, empty, background | its colour, a bar's / the dots' last colour, the unlit
part's, its panel's ('none': no panel) |
size, bold, blink, seconds | 's' 'm' 'l' 'xl'; bold
text; blinks from that second; goes by itself after that long |
32 at once; recordings keep the ones shown to everyone.
Areas and named points
A map may have areas — the map editor's ⬚ Zone tool with the effect "area", and a name: boxes or cylinders that
do nothing to the game and tell a script what crosses their edge (onBallArea, onPlayerArea): the pitch's
lines, a penalty box, a team's half. And named points (the ✚ Point tool): spots a script finds by name.
room.getAreas() // [{index, name, shape, x, y, z, w, d, h, yaw}]
room.getPoints() // [{name, x, z}] — mirror copies share their name
room.isInArea('box', { x, z }) // inside the first area of that name (or its index)?
// out over the touchline (the pitch is an area named "pitch"):
room.onBallArea = (ball, area, inside, at) => {
if (area.name === 'pitch' && !inside && (at.edge === 'z+' || at.edge === 'z-')) {
const team = at.lastTouch && at.lastTouch.team === 'red' ? 'blue' : 'red';
room.sendAnnouncement(`Throw-in ${team}`);
}
};
Barriers
Lines, circles and boxes some players stay behind, outside or inside — the kickoff rule's geometry, yours. A disc on the wrong side is put on the nearest allowed spot; every screen applies them alike; the ball is never held by one.
// a throw-in: Red waits behind a line 4.7 m inside the touchline, drawn in Blue's colour, until the ball is kicked
room.setBarrier('throw', { team: 'red', line: { a: { x: -40, z: 15.3 }, b: { x: 40, z: 15.3 }, side: { x: 0, z: 0 } },
until: 'kick', color: '#3e8bff' });
room.setBarrier('corner', { team: 'blue', circle: { x: 40, z: 22, r: 14 }, until: 'kick' }); // out of a circle
room.setBarrier('keeper', { players: [id], box: { x: 38, z: 0, w: 1, d: 8.3 }, keep: 'in', until: 'kick' }); // held in a box
room.setBarrier('throw', null) room.clearBarriers() room.getBarriers() // [{id, …, lifted}]
Keys: team ('red' 'blue' 'all') or players: [ids]; one shape — line: {a, b, side}
(they stay on side's side of the segment), circle: {x, z, r}, box: {x, z, w, d, yaw}; keep
('out' / 'in', circles and boxes); until ('kick' or 'touch': lifted the tick a ball is
kicked / touched); seconds; color (drawn — none: unseen); style ('ground': a glowing band on the
grass with a light running along it, the default — or 'wall': a wall of light height m tall, a glowing band under it). A
drawn barrier fades in, and fades out when it lifts. 16 at once; a field change takes them away.
Markers
The same shapes, drawn for show only — they hold nobody: an offside line, a target, a finish line, the spot a set piece is taken from.
// the offside review's line: a wall of light across the pitch where the attacker was
room.setMarker('offside', { line: { a: { x: 21, z: -20 }, b: { x: 21, z: 20 } }, style: 'wall', height: 2.2, color: '#e5484d' });
room.setMarker('target', { circle: { x: 30, z: 0, r: 2 }, color: '#ffd23f', seconds: 5 }); // a glowing ring for 5 s
room.setMarker('offside', null) room.clearMarkers() room.getMarkers()
Keys: one shape — line: {a, b}, circle: {x, z, r}, box: {x, z, w, d, yaw}; style
('ground' / 'wall'); height (a wall's, m); color (white when left out); seconds (it goes by
itself after that long of game time). 16 at once; a field change takes them away; recordings keep them.
Player effects
room.setPlayerEffect(id, 'sprint', { speed: 1.6, accel: 1.8, seconds: 1 }) // multipliers: speed, accel, jump, kick, size
room.setPlayerEffect(id, 'tired', { speed: 0.87, seconds: 3 })
room.setPlayerEffect(id, 'sprint', null) room.getPlayerEffects(id) // [{name, …, seconds}]: the seconds left
Several multiply (4 at once a player); they count down in the game's ticks and every screen plays them alike — a sprint, a slowed fouled player, a giant for ten seconds.
Card badges and suspensions
Small marks on a player's card in the room menu (Esc), on a line under their name: a text, an icon, a timer, or any of them together — a yellow card, a red card counting down, "MVP", a streak. Everyone in the room sees them.
const CARD = 'M8.6 2.4l8.4 1.5c.8.1 1.3.9 1.2 1.7l-2.5 14.3c-.1.8-.9 1.3-1.7 1.2L5.6 19.6c-.8-.1-1.3-.9-1.2-1.7L6.9 3.6c.1-.8.9-1.3 1.7-1.2z';
room.setPlayerBadges(id, [
{ icon: { paths: [{ d: CARD, fill: '#ffd23f' }] }, title: 'Yellow card' }, // an icon
{ icon: { paths: [{ d: CARD, fill: '#ff3b30' }] }, time: { seconds: 60 }, color: '#ff3b30', bold: true, size: 13 }, // + a timer: 01:00, 00:59 …
{ text: 'MVP', color: '#ffd166', bold: true }, // a text
{ text: 'streak', time: { seconds: 0, mode: 'up' } }, // a timer counting up: 00:00, 00:01 …
]);
room.setPlayerBadges(id, null) room.getPlayerBadges(id)
room.suspendPlayer(id, 60) // off to the spectators for 60 s of game time, their place kept; null: ends it now
room.getSuspensions() // [{id, team, seconds}]
A badge: text (14 characters at most, one line), icon, time ({seconds, mode: 'down' | 'up'},
up to 3600 s, on the game's clock — it stops while the game is paused), color (the text's and the icon's),
bold, size (the text's and the timer's, px: 11 to 13 — 12 by default —, the most the badges' line holds
without the card growing), title (shown on hover). Four a player at most. A card keeps its size whatever you put on it: the first
badge always shows its icon and its timer (its text cut with "…" when short of room), the others show only when they fit
whole — put the one that matters first. Badges never change the card's background or the name: a card's style is the
player's own.
An icon is SVG path data that the game draws: { view: [x, y, w, h], paths: [{ d, fill, stroke, width }] }
(view is [0, 0, 24, 24] when left out; 4 paths of 600 characters at most; a plain string is one path in the
badge's colour). Only drawing commands (M L H V C S Q T A Z and numbers) — never SVG markup, pictures or links. Any
24 × 24 icon of a free icon set (Material Symbols, Lucide, Tabler…) works: copy its d.
suspendPlayer(id, seconds) sends a player on Red or Blue to the spectators while a game runs — a sin bin. Their
place is kept (the standard room does not fill it); when the time is up they go back to their team if it is still a player
short — if an admin put someone else there meanwhile, they stay out. Putting them on a team yourself ends it, and so does the
game stopping (they stay a spectator). onPlayerSuspensionEnd(player, back) tells you. Show the time with a badge
(time: {seconds}): both run on the same clock.
Light
Every field has a global light — the sun: its direction, height, strength, colour and shadows — and an ambient light from everywhere; a map may switch the global light off (a night). Any 3D object can be a light source: a point (all around its middle) or a spot (a cone along the object's down axis: turn and tilt the object to aim it), with its colour, strength, reach, and how much its own object glows. Maps get them in the map editor (Look → Light, and an object's Light section, where it can also get a name); a script reads them all and changes any of them as the game goes — a goal, a kickoff, the night falling. Every change fades on every player's screen over the seconds the script asks, joiners see the light as it is, and recordings keep it. It is only the look: nothing in the game plays differently. Players may turn the global light's direction for themselves (⌨ Controls) — and nothing else.
room.getLights() | every light source now: {id, name, from, x, y, z, kind, on, color, intensity, range, angle, glow, shadows}
— id is "map:<index>" for a map's object (from: 'map') or your object's id
(from: 'script'); name is the one given in the editor; values with your changes over the map's |
room.getGlobalLight() | {on, turn, elevation, intensity, color, ambient, shadows} |
room.setLight(ids, props, seconds) | changes light sources — one id, a list of ids, or '*' (all of them) —
fading over seconds (0: at once). props: any of on, color ('#rrggbb'),
intensity (0–12), range (m), angle (a spot's cone, °), glow (0–3) |
room.setGlobalLight(props, seconds) | changes the global light and the ambient: any of on,
turn (° around the pitch), elevation (° above the horizon), intensity (0–5),
color, ambient ('#rrggbb'), shadows |
room.resetLights(seconds) | every light back to the map's own (fading) |
room.setObject(id, {…, light}) | a light of your own: an object with
light: {kind: 'point' | 'spot', on, color, intensity, range, angle, glow, shadows} (opacity: 0:
a light with no lamp). setLight then changes it by its id; removing the object takes its light |
Your changes stay over the map's values until you change them again or call resetLights; a field change starts
from the new map's light. A map has at most 32 light sources (each costs every player a little); shadows from a light source
cost more — keep them for the ones that matter. A goal's flash in the scorer's colour, then back:
room.onTeamGoal = (team) => {
const c = team === 'red' ? '#ff3b2f' : '#2f7bff';
const towers = room.getLights().filter(l => l.name === 'tower').map(l => l.id);
room.setGlobalLight({ color: c, intensity: 1.2 }, 0.12); // the whole stadium, at once
room.setLight(towers.length ? towers : '*', { color: c, intensity: 9 }, 0.12);
setTimeout(() => room.resetLights(1.4), 2400); // and back to the map's light
};
Two built-in fields show it: Night (no sun, six street lamps — made in the map editor alone) and Floodlights
(an evening stadium whose lights have names: tower, goal-left, goal-right,
led), played with goal-lights.js: every goal turns the stadium the
scorer's colour, the light over the goal strobes and the LED boards chase round; the towers come on one after another at a
kickoff; a win ends in the winner's colour.
Bots
room.addBot('red') adds a bot to a team (it takes one of the room's places — or, when people fill them all,
some of them sitting out, one more, up to 24 players in all: a person joining a full room makes the newest bot leave);
room.removeBot(id) takes it away. A second argument sets what an admin sets on the bot's card, each part
optional: position ('auto', the team decides — or 'GK', 'DM',
'AM', 'ST'), level (1 the weakest to 5) and brain ('smart';
'light', the same football thought out less often — far cheaper when a room has many bots; 'press',
marking a player each and pressing high) — room.addBot('red', { level: 4, brain: 'light' }). Left out, a bot
plays as Auto, level 3, Smart; anything else throws. A player object says a bot's own as botPos,
botLevel and botBrain. A bot plays football on its own, with its team: on a field with a goal
each a team lines up in positions (keeper, midfielders, striker), the player who would reach the ball first goes for it and
the others keep their places, following the play; on the ball it shoots, passes, dribbles, clears or lobs as the moment
suggests. On a map with energy it boosts and picks up pads. Two orders change that, for games your script invents:
room.setBotTarget(id, {x, z}) | where the bot waits: it goes to that point and stays there, and plays the
ball while the ball is within 2.5 m of it (a keeper in front of a goal, a defender of a zone) — whoever is closer, it
goes for those balls itself — or when it is the player nearest the ball. null: it plays with its team again. |
room.setBotAim(id, {x, z}) | where the bot sends the ball, instead of the other team's goal (a player's
goal in 6man, a target, a teammate). null: the goal again. |
Orders are for bots only (a person throws), stay until changed, and end when the bot leaves. The 6man scripts give every bot its own goal to guard and the leader's goal to shoot at:
room.setBotTarget(id, { x: g.middle.x - g.normal.x * 2, z: g.middle.z - g.normal.z * 2 }); // 2 m in front of its goal
room.setBotAim(id, { x: leader.middle.x, z: leader.middle.z });
If your rules have offside or throw-ins, tell the bots, so they play by them:
room.setBotHints({ offside: 4, outOfPlay: true }) — offside counts once either team has 4 players (the bots stay
onside and never pass to a teammate who is offside), and a ball over the pitch's lines goes to the other team (they keep
it in). null forgets it; room.getBotHints() reads it. A ball your script holds for a team
(setBallProperties({ hold: true, holdFor: team })) is that team's set piece anyway: its nearest bot takes it, passing or putting it
into the pitch, and the other team's bots leave it alone. Real Soccer's rules script calls it.
Captains
Name a team's captain with room.setTeamCaptain('red', id) (they must be on that team). A captain can
open the room menu (Esc) and drag a spectator who is not AFK onto their own team — never someone from the other team;
the room checks every pick. onPlayerTeamChange(player, byPlayer) tells you who picked whom.
room.setTeamCaptain('red', null) ends it. The standard script uses this for its picking turns (below).
AFK players
A player on a team who presses no key for 30 seconds while the ball is in play is marked AFK; so is a player who
types !afk, or one your script marks with room.setPlayerAfk(id, true). Everyone sees "💤 AFK"
on their card. Pressing a key in play, typing !afk again, or clicking the tag on their own card brings them
back. player.afk and onPlayerAfkChange let your script react (move them out, skip them…).
Three seconds before, the player gets a warning popup; it closes as soon as they press a key, or when the game is paused or stopped. Only time in play counts: after a goal the count waits, and a pause (with its countdown) or a stopped game starts every count again from zero.
room.setAfkSeconds(60) // the room's AFK time: a minute (up to 3600)
room.setAfkSeconds(0) // never by idling (!afk and your marks still work)
room.setAfkSeconds(null) // back to the game's 30 seconds
room.getAfkSeconds() // what it is now: 30 unless you changed it
room.setPlayerAfkPaused(id, true) // never set AFK (nor warned) for idling: a player your script keeps waiting; false: counted again
room.onPlayerAfkChange = (player, afk, by) => {
if (afk && by === 'idle' && player.team !== 'spec') room.setPlayerTeam(player.id, 'spec');
};
With a time of four seconds or less there is no warning popup (it would come before the player could have moved).
Admins
- Your script is the host: it can do everything (
setPlayerAdmin,kickPlayer…). - Admins (made in the room) move players, start and stop games, change the field and limits, kick and ban players who are not admins.
- The room's admins named with
admins/room.setRoomAdmins([…])(account ids — theaccountof a logged-in player) are admin as soon as they join, can also make admins and clear bans, but never kick, ban or take admin from another admin.
Replays
room.startRecording() records the game; await room.stopRecording() gives the file's bytes
and room.saveReplay(bytes, 'name') keeps them — a download in the browser tab. Anyone can watch a .rbr file with ▶ Watch replay on the room list.
League matches: statistics for your league's bot
Running a league? Make its match room a league match room: every match gets a short match code as it begins —
your bot can follow it live by that code — and is published under it once played to its end (a match stopped before its end
reads stopped), so your bot fetches the score, the goals and the line-ups instead of someone copying them by hand. Switch it on with RosikRoom.create({ league: true }),
room.setLeague(true) (room.getLeague() reads it), or the room menu's League match (admins).
- The room's page must be logged in to a RosikBall account: it publishes as the room's host. The site checks with the
lobby that this account hosts that room and which players it let in — a player is marked
account: trueonly then. - The record is the game's own (its goals, its clock), never a script's. Everyone in the room sees that it is a league room;
only the room's admins are told the codes (their chat and room menu — one made admin later gets them too).
onLeagueMatchStart(code)andonMatchPublished(code, report)give them to your script,onLeagueChange(on, byPlayer)says it was switched. - A match is kept for a year; at most 60 matches an hour start per host.
Reading them — no login, from any site or server:
GET https://rosikball.com/api/league/matches/<code>
{ "ok": true, "match": {
"code": "K7MX2PQR", "state": "final", "at": 1794480000000, "room": "AB12C", "host": "Organiser", "source": "host",
"field": "futsal", "map": "Futsal", "seconds": 300, "end": "time", "overtime": false,
"limits": { "time": 5, "score": 0 }, "winner": "red", "score": { "red": 3, "blue": 1 },
"possession": { "red": 54, "blue": 46 },
"goals": [ { "t": 42.5, "team": "red", "scorer": "Ana", "assist": "Bo", "own": false, "golden": false }, … ],
"players": [ { "nick": "Ana", "team": "red", "seconds": 300, "goals": 2, "assists": 0, "ownGoals": 0, "account": true, "pid": "p_3fa9c1d27e8b4a05" }, … ] } }
// while it is played: "state": "live" — the score, goals, line-ups, clock and possession so far, "updated" (when the host last
// said it), no "winner" yet, never cached; stopped before its end: "state": "stopped" with no numbers
GET https://rosikball.com/api/league/matches?room=<room code>&limit=20
{ "ok": true, "room": "AB12C", "matches": [ { "state", "at", "room", "field", "map", "score", "winner", "seconds" }, … ] } // newest first, never their codes
GET https://rosikball.com/api/league/live?room=<room code>
{ "ok": true, "room": "AB12C", "open": true, "at": 1794480030000, "live": {
"state": "live", "field": "futsal", "map": "Futsal", "seconds": 30, "overtime": false, "limits": { "time": 5, "score": 0 },
"score": { "red": 1, "blue": 0 }, "possession": { "red": 58, "blue": 42 }, "goals": [ … ], "players": [ … ] } }
// "live" is also { "state": "finished", "score": { … } } once a match is published,
// { "state": "stopped" } when one was stopped before its end, or null
The live view is the match being played: the host sends it on every goal and every 10 seconds of play. It is never stored nor cached — ask again a few seconds apart. A match read by its code while it is played is the same view. What a room's code reads never gives a match's code: anyone in a room knows the room's code, and the codes are its admins' alone.
t and seconds are seconds of play; possession is per cent of the time each team had the
ball (null when unknown); a goal's team is the team it counts for (own: its scorer put it in their own
net); golden is overtime's winner. A room code is reused for many matches: keep the match codes.
Who is who. A player with account: true also has a pid, their public player ID: it names
the account, so it stays the same when they change their nickname (they can once a week) — key your records by it, not by the nickname.
It is opaque (nothing about the account can be worked out from it) and the same everywhere: a player's public profile gives it too —
GET https://rosikball.com/api/players/<nickname> → { "ok": true, "profile": { "nick": "Ana", "pid": "p_3fa9c1d27e8b4a05", … } }
(and the search, /api/players?q=, one pid a player) — so a bot finds a player's pid from their current
nickname once and follows it from then on. A guest has none. Matches published before 14 November 2026 have no pid.
Scripted maps
A map can bring its own script: its rules travel with it. A room that plays a scripted map runs the map's script while the map is played — 6man gives every player a goal of their own, Floodlights puts on its light show, Real Soccer adds throw-ins, corners, fouls and offside. A map's script either runs the room meanwhile (a full script: the room's own script waits) or only adds rules to the match beside the room's own script (rules only) — see the two kinds. Everyone sees the map marked SCRIPTED and, in the room menu under the field, what runs.
Writing one
In the map editor, the Script tab: 📜 Add a script (or load a .js
file), write it with the RosikRoom API of this page, ✓ Check it (a trial game in the sandbox) — the 3D preview
runs it as a room would, and so does a test room with friends. Save the map and every room that plays it runs it.
// the map's own rules (RosikRoom.create gives the room as it is: only the limits and the teams lock apply)
const room = RosikRoom.create({ scoreLimit: 5 });
room.onPlayerJoin = (player) => {
// everyone already in when the map was picked "joins" first: the script knows the whole room
room.sendAnnouncement(`Welcome, ${player.name}!`, player.id);
};
room.onTeamGoal = (team, scorer) => {
if (scorer) room.setPlayerCard(scorer.id, [{ text: 'scored on this map', bold: true }]);
};
What a map's script may do
The map may be anyone's, played in anyone's room, so its script has a game's powers, never the room's:
| It may (a full script) | It may not (these throw) |
|---|---|
| move players between the teams, captains, AFK marks; start, stop and pause games; the time and score limits; score goals; objects, the scoreboard, goal texts, discs, balls, light, avatars, disc colours, card popups; bots; announcements | kickPlayer, setPlayerAdmin, mutePlayer, clearBans,
setPassword, setRoomName, setPublic, setMaxPlayers,
setDiscord, setRoomAdmins, setAfkSeconds, setField,
setMap, recordings and saveReplay (setMapScripts only returns
false) |
Two kinds: a full script or rules only
The table above is a full script's, the default: it runs the room while the map is played. A script marked
Rules only (the Script tab's checkbox; script.role: 'rules' in the map file) runs beside the
room's own script instead, and leaves the room to it:
| Full script (the default) | Rules only | |
|---|---|---|
| Built-in examples | 6man, Floodlights | Real Soccer |
| The room's own script (if you run one) | waits while the map is played: its handlers are not called and its
actions return false; when the map's script stops it goes on and hears onPlayerLeave /
onPlayerJoin for who left and came meanwhile | keeps running beside it; both hear every event |
| Who fills the teams | the map's script (the room's own way of picking teams is off) | the room — its script or its admins — as on any field |
| Who starts and stops games | the map's script | the room |
| Time and score limits | the map's; the script may change them (its RosikRoom.create applies only
timeLimit, scoreLimit, teamsLock) | the map's or the room's; the script may not change
them (its RosikRoom.create applies nothing) |
| Moving players between teams | anywhere | only to the spectators (a red card) |
| Captains, bots, the teams lock | the script may set them | may not |
| AFK players | the game still marks idle players AFK (onPlayerAfkChange), but what happens to them is the
map script's: your room script's own AFK rules do not run meanwhile | your room script handles them as usual; the map's script may not mark anyone AFK |
Pauses and freezes (pauseGame) | may | may |
| On the pitch: objects, barriers, markers, balls, discs, scoring, HUD widgets, sounds, light… | may | may |
Which to write: rules only for a Red v Blue match with rules of its own (set pieces, fouls, powers) — any room's usual way of filling the teams and starting the games still works with it. A full script for a different kind of game (a goal per player, rounds, knock-outs) that a usual Red v Blue room cannot run — and then it must do everything the room's script would have: fill the teams, start and stop the games, deal with AFK players.
It never hears team or private messages (onPlayerChat gets the public ones). It runs in the
sandbox wherever the room is run — in the browser of the player who hosts —
with its limits; in a player's browser it may also use at most half of one processor core over 30
seconds. A script that fails, hangs or goes over a limit is stopped and the room says why.
In the room
- View (anyone) shows the script's text. Admins Turn off the map's script (the room's own rules
again), Turn on again, or Load script…: a
.jsof their own for this field, with the same powers as a map's. Only while no game runs, like the field; the chat says who did it. - Picking a scripted map, an admin may take it without script (Find a map… has a button on its card; Load map… asks): the field comes in with its script turned off.
- When the map's script stops — another field, turned off, failed — what it did to the game goes too (its objects, scoreboard, goal texts, light changes, balls, disc colours, card popups, bot orders, captains); after a full script the room's own script goes on (a rules-only one never stopped it).
room.setMapScripts(false) // maps' scripts never run in this room (and admins cannot load one); true: they may again
room.getMapScript() // {allowed, map: the field's script name or null, run: 'map' | 'custom' | null, name, off, error}
The examples below call
room.setMapScripts(false) at their start: run as a room's own script, they already are the field's script;
as a map's script, the call does nothing.
Familiar calls: discs, flags, stadiums, units
If you have written headless room scripts for other disc football games, these calls and events will be familiar — they work beside the ones above, under the names you know.
const room = RosikRoom.create({ roomName: 'Pub', playerName: 'Referee', noPlayer: false })
// noPlayer (true by default): the host is no player; false: a player of its own, playerName
room.sendChat('Welcome!', toId) // the host writes in the chat as a player does, under playerName ('Host'), marked HOST
room.sendAnnouncement('Goal!', null, 0xFFD166, 'bold', 2) // colour, style ('normal' 'bold' 'italic' 'small' 'small-bold'
// 'small-italic'), sound (0 none, 1 the chat's blip, 2 a notification)
room.setPlayerTeam(id, 1) // 0 / 1 / 2 = spectators / red / blue, as well as the names
room.clearBan(id) // one ban lifted: the player banned with that id may join again
room.reorderPlayers([id, …], true) // those players first (false: last) — the menu, getPlayerList, each team's kickoff spots
room.setCustomStadium(hbsText) // a .hbs stadium file's text (or a map's): setMap
room.setDefaultStadium('Big') // a built-in field by its name: 'Classic' 'Easy' 'Small' 'Big' 'Rounded' 'Big Easy' 'Big Rounded' 'Futsal'…
room.setKickRateLimit(2, 0, 0) // min frames between two kicks, a kick saved up every `rate` frames, `burst` saved at most
// (frames of 1/60 s); left out: 2, 0, 0; all 0: none (the room's default)
room.getKickRateLimit() // {min, rate, burst} | null — admins also have /kick_ratelimit in the chat
room.setTeamColors('red', 60, 0xFFFFFF, [0xC8102E, 0x111111, 0xFFD166])
// a team's discs in 1–3 bands at `angle` degrees, the avatar in textColor; setTeamLook(team, null) undoes it
room.getDiscCount() // the discs: the balls (getBalls' order), then the players on the pitch (the room's order)
room.getDiscProperties(0); room.setDiscProperties(1, { xspeed: 4 }) // by that index: a ball's or a player's
A disc's own settings — setPlayerDiscProperties(id, props), setDiscProperties(index, props),
setBallProperties(props, id), setBall(id, props); null puts one back to the map's, and a player's
are dropped when they change team and at each new game:
room.setPlayerDiscProperties(id, {
radius: 0.8, // m (0.1–3)
bounce: 0.5, // bCoeff too
mass: 4, // kg — or invMass (1 / mass; 0: as heavy as can be)
damping: 0.6, // the speed it loses in a second (0–0.999): smaller glides longer and runs faster
gravity: 22, // its own, down (m/s²)
xgravity: 0, zgravity: 3, // a pull along the floor (m/s²): x along the field, z across
cGroup: room.CollisionFlags.red | room.CollisionFlags.c0, // what the disc is
cMask: room.CollisionFlags.wall | room.CollisionFlags.ball, // what it collides with
color: -1 // not drawn (a colour, 0xRRGGBB or '#rrggbb': its colour)
});
room.setBallProperties({ cMask: room.CollisionFlags.wall, hidden: false, xgravity: 2 }) // a ball through the players
room.CollisionFlags: ball 1, red 2, blue 4, redKO 8, blueKO 16, wall 32, all 63, kick 64, score 128, c0 … c3.
Two discs meet when each one's cGroup is in the other's cMask; wall is the map's walls, posts, nets
and objects — the floor and the ceiling stop every disc. A ball without kick cannot be kicked, one without
score never scores; a player whose cGroup lacks redKO / blueKO is not held by the
kickoff's barrier.
Units: RosikBall measures in metres and seconds, where those scripts count pixels and frames.
| Pixels and frames | RosikBall |
|---|---|
| px | m = px ÷ 30 |
| x, y | x, z (y is up) |
| speed, px per frame | m/s = × 2 (60 frames a second) |
| gravity, px per frame² | m/s² = × 120 |
| damping, kept per frame | lost per second = 1 − damping60 (players' 0.96 → 0.91, the ball's 0.99 → 0.45) |
| invMass | mass = 1 ÷ invMass |
| teams 0 1 2 | 'spec' 'red' 'blue' (the numbers are taken too) |
Not here: a geo override, room tokens and captchas — our lobby guards the rooms.
Examples
Commands
room.onPlayerChat = (player, text) => {
if (!text.startsWith('!')) return true; // a normal message: shown
if (text === '!score') {
const s = room.getScores();
room.sendAnnouncement(`Red ${s.red} : ${s.blue} Blue`, player.id);
} else if (text === '!bb') {
room.kickPlayer(player.id, 'bye!', false);
}
return false; // commands are not shown in the chat
};
Cards that show statistics
const stats = new Map(); // player id → {goals, assists}
const showCard = (id) => {
const s = stats.get(id) || { goals: 0, assists: 0 };
room.setPlayerCard(id, [`Goals: ${s.goals} · Assists: ${s.assists}`, ...(s.goals >= 3 ? [{ text: '⭐ Hat-trick', color: '#ffd166', bold: true }] : [])]);
};
room.onPlayerJoin = (p) => showCard(p.id);
room.onTeamGoal = (team, scorer, assist, ownGoal) => {
for (const [p, key] of [[scorer, 'goals'], [assist, 'assists']]) {
if (!p || ownGoal) continue;
const s = stats.get(p.id) || { goals: 0, assists: 0 };
s[key]++;
stats.set(p.id, s);
showCard(p.id); // every menu shows the new numbers
}
};
Goals and statistics
const goals = new Map(); // account (or name) → goals
room.onTeamGoal = (team, scorer, assist, ownGoal) => {
if (!scorer || ownGoal) return;
const key = scorer.account || scorer.name;
goals.set(key, (goals.get(key) || 0) + 1);
room.sendAnnouncement(`⚽ ${scorer.name} (${goals.get(key)} today)`);
};
6man: a goal for each player
Two complete scripts play the 6man rules on the 6man field (or any field with two goals or more): every player
owns a goal and has 3 points, every goal let in costs one, at 0 you are out — the last player standing wins. They show
what the field functions above can do: each goal gets a floor marker and a frame in its owner's colour (setObject,
setGoalColor), each
disc an avatar of the same colour, everyone starts every kickoff in front of their own goal
(setPlayerSpawn), the points are on the scoreboard (setScoreboard) and hovering it lists the points and the
latest goals (setScoreboardPopup), leaving, going to the spectators or going AFK during a game loses it
(onPlayerLeave, onPlayerTeamChange, onPlayerAfkChange), the game's
"RED scores" texts are off while it plays (setGoalMessages(false)), and onTeamGoal's
where.goal says whose goal it was. Each disc is in its owner's colour (setPlayerColor).
- 6man-empty-goal.js — a player who is out leaves the pitch and their goal stays open: whoever scores in an empty goal loses a point.
- 6man-closed-goal.js — a player who is out leaves the pitch and a wall shuts their goal: the ball bounces off it.
Penalties: a shoot-out
penalties.js is the Penalties field's script: a penalty shoot-out with the real
rules — five kicks each at one goal, then sudden death. Before each kick it gives the goal to the keeper's team
(setGoalTeam), so a goal counts for the kicker's team like any goal; an invisible wall that stops only the players holds the
keeper on his line until the ball is kicked (setObject with stops: 'players'); everyone else waits in the centre
circle (setPlayerSpawn, setPlayerDiscProperties) and out of the AFK count (setPlayerAfkPaused); the
scoreboard shows each team's kicks.
Real Soccer
real-soccer.js is the Real Soccer field's rules (a rules script: the room's own
script still fills the teams): throw-ins, corners and goal kicks where the ball goes out over the pitch's lines
(onBallArea on the map's areas, its named points), the ball held on its spot for the team taking it
(setBallProperties with hold), the other team kept away (setBarrier), a countdown of dots over the
taker (setHud) and a free ball when nobody takes it (setTimer); passes that make the ball stronger; slides and
sprints charged by holding kick (onPlayerButton, setPlayerEffect); fouls (onPlayerContact), free
kicks and penalties; cards on the players' cards (setPlayerBadges) — a red one sends its player off for a minute
(suspendPlayer), its time counting down under the name; offside, shown with a freeze (pauseGame with
seconds); the referee's whistles and the final horn (playSound). Change its RULES at the top.
Goal lights
goal-lights.js plays with the light (see Light) on the Floodlights field — or any field: it finds lights by the names the map gives them and leaves out what a map does not have.
The standard room
standard-room.js is a complete room, ready to run:
players wait in line, captains pick the teams (the first in line who is not AFK captains an empty team; a short
team picks one player at a time — during a game too, when a player leaves: the game waits —, the next in line is picked for a captain who
waits 20 seconds), the game starts by itself, winners stay and the losers go to the back of the line — and when nobody
else waits, the same players are dealt into new teams at random rather than play the same match again —, a team left with
nobody gets one of the other team's players, idle players sit out (its afkSeconds rule
is the game's AFK time, so the warning popup comes first; a team that does not take its kickoff within that time sits
out too, whatever its size), !afk,
!back, !bb, and every game is recorded. Change its ROOM and RULES at
the top, or use it as a starting point for your own.
The sandbox and its limits
A map's script runs in a sandbox: the RosikRoom API and plain JavaScript, nothing else —
no network (fetch, WebSocket and the like do not exist there), no storage, no WebAssembly. Reading the room
is instant; actions go to the room. So that a map cannot hurt the room that plays it, it is rationed (a map's script has
fewer powers than a room's own: the room's settings are not among them):
| What | Limit |
|---|---|
| All actions together | a burst of 120, then 20 a second |
sendAnnouncement, playSound | a burst of 40, then 8 a second |
setHud, clearHud | a burst of 60, then 20 a second |
setRoomName, setPublic, setPassword, setMaxPlayers,
setDiscord, setRoomAdmins | a burst of 10, then 1 a second |
setField, setMap, addBot, removeBot, startRecording,
stopRecording | a burst of 6, then 1 every 2 seconds |
setObject, removeObject, clearObjects, setScoreboard,
setPlayerAvatar, setGoalMessages, setPlayerColor, setPlayerLook, setTeamLook, setThreeMen, setEnergyRules, setPlayerEnergy, setPlayerCard, setScoreboardPopup,
setPlayerSpawn, setGoalColor, setGoalTeam, setPlayerAfkPaused, setBotTarget, setBotAim, setBotHints,
setBall, removeBall, clearBalls, setBarrier, clearBarriers, setMarker, clearMarkers,
setPlayerEffect, setPlayerBadges, suspendPlayer | a burst of 60, then 8 a second |
setLight, setGlobalLight, resetLights (a list of ids, or '*', is one call) | a burst of 60, then 10 a second |
saveReplay | a burst of 3, then 20 an hour; RosikBall replays only, 16 MB each |
| An action's arguments | 16,000 characters (a map for setMap: 192,000) |
| Timers waiting at once | 500 |
| Script size | 64 KB |
| Processor | in a player's browser, half of one processor core on average over 30 seconds |
A script that starts in a room with players already in it hears onPlayerJoin for each of them first.
An action over its limit is refused: it returns false. The room stops the script — without disconnecting
anyone, and the chat says why — when it stops answering for 4 seconds (an endless loop; it has 15 seconds to start),
throws more than 50 errors in a minute or keeps asking for more than 600 refused actions in a minute. Scripts you run
yourself as the room's script (in a browser tab) are not rationed: they use your own machine.
What a script cannot do
A script runs on the host's machine and can do exactly what the room's host can — nothing more for anyone else. What it
changes on the field (discs, balls, the kick limit) reaches every player, so every game predicts the same match; it cannot
see other players' screens or touch their accounts. Keep handlers light, especially onGameTick: a slow script slows the room for everyone.
Please respect the terms: no impersonating RosikBall or other players, no spam on the room list.