RosikBall

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

  1. 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.
  2. Open the browser's console (F12 → Console).
  3. Paste your script and press Enter (the first time, the browser asks you to type allow pasting before 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).

GroupCommands
The roomRosikRoom.create(config)
ReadinggetPlayerList() getPlayer(id) getScores() getBallPosition(id) isGameRunning() getTeamCaptain(team) getRoomCode() getRoomLink() getMap() getScoreboard() reclaimKey
PlayerssetPlayerTeam(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 badgessetPlayerBadges(id, badges) getPlayerBadges(id)
GamesstartGame() stopGame() pauseGame(on, by?) setTimeLimit(minutes) setScoreLimit(goals) setField(name) setMap(map) setCustomStadium(text) setDefaultStadium(name) setKickRateLimit(min, rate, burst) getKickRateLimit()
Room settingssetRoomName(name) setPublic(on) setPassword(text) setMaxPlayers(n) setDiscord(link) setPlatforms(rule) getPlatforms() setLeague(on) getLeague()
Chat, soundssendAnnouncement(text, toId, style) sendChat(text, toId) playSound(name, to)
Discs, flagsgetDiscCount() getDiscProperties(index) setDiscProperties(index, props) setTeamColors(team, angle, textColor, colors) CollisionFlags InputFlags
The fieldgetGoals() 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)
BallsgetBalls() setBall(id, props) removeBall(id) clearBalls() — and getBallProperties(id) / setBallProperties(props, id)
Game timerssetTimer(id, seconds, {repeat, paused}) clearTimer(id) clearTimers() getTimers()
HUD widgetssetHud(id, widget) clearHud() getHud()
Areas and pointsgetAreas() getPoints() isInArea(area, point)
BarrierssetBarrier(id, barrier) clearBarriers() getBarriers()
MarkerssetMarker(id, marker) clearMarkers() getMarkers()
Player effectssetPlayerEffect(id, name, effect) getPlayerEffects(id)
LightgetLights() getGlobalLight() setLight(ids, props, seconds) setGlobalLight(props, seconds) resetLights(seconds) — and setObject with a light
BotsaddBot(team, opts?) removeBot(id) setBotTarget(id, point) setBotAim(id, point) setBotHints(hints)
ReplaysstartRecording() await stopRecording() saveReplay(bytes, name)
Scripted mapssetMapScripts(on) getMapScript()
EventsonRoomLink 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.

HandlerWhen
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.reclaimKeythe 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, _ - . :).

CallWhat 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}]
KeyWhat it is
type'text' 'timer' 'bar' 'dots'
at / attacha 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)
tonull (everyone), 'red', 'blue' or a player's id: only they are sent it
iconan 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, countits 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, backgroundits 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

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).

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 examples6man, FloodlightsReal 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 meanwhilekeeps running beside it; both hear every event
Who fills the teamsthe 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 gamesthe map's scriptthe room
Time and score limitsthe 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 teamsanywhereonly to the spectators (a red card)
Captains, bots, the teams lockthe script may set themmay not
AFK playersthe 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 meanwhileyour room script handles them as usual; the map's script may not mark anyone AFK
Pauses and freezes (pauseGame)maymay
On the pitch: objects, barriers, markers, balls, discs, scoring, HUD widgets, sounds, light…maymay

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

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 framesRosikBall
pxm = px ÷ 30
x, yx, z (y is up)
speed, px per framem/s = × 2 (60 frames a second)
gravity, px per frame²m/s² = × 120
damping, kept per framelost per second = 1 − damping60 (players' 0.96 → 0.91, the ball's 0.99 → 0.45)
invMassmass = 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).

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):

WhatLimit
All actions togethera burst of 120, then 20 a second
sendAnnouncement, playSounda burst of 40, then 8 a second
setHud, clearHuda burst of 60, then 20 a second
setRoomName, setPublic, setPassword, setMaxPlayers, setDiscord, setRoomAdminsa burst of 10, then 1 a second
setField, setMap, addBot, removeBot, startRecording, stopRecordinga 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, suspendPlayera 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
saveReplaya burst of 3, then 20 an hour; RosikBall replays only, 16 MB each
An action's arguments16,000 characters (a map for setMap: 192,000)
Timers waiting at once500
Script size64 KB
Processorin 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.