Omegga API

The Omegga global (and the omegga passed to a plugin constructor) implements OmeggaLike. It is an event emitter, so everything in Events is available on it too.

OmeggaLike

Extends OmeggaCore, LogWrangling, InjectedCommands, MockEventEmitter.

writeln

writeln(line: string): void

getPlugin

getPlugin(name: string): Promise<PluginInterop | null>

get a plugin’s name, documentation, and loaded status If run in an unsafe plugin, the emitPlugin method sends events from an “unsafe” plugin

_{Declared in src/plugin.ts.}

OmeggaCore

getPlayers

getPlayers(): { id: string; name: string; displayName: string; controller: string; state: string; }[]

get a list of players

Returns list of players {id: uuid, name: name} objects

getPlayer

getPlayer(target: string): OmeggaPlayer | null

find a player by name, id, controller, or state

findPlayerByName

findPlayerByName(name: string): OmeggaPlayer | null

find a player by rough name, prioritize exact matches and get fuzzier

getHostId

getHostId(): string

get the host’s ID

Returns Host Id

broadcast

broadcast(...messages: string[]): void

broadcast messages to chat messages are broken by new line multiple arguments are additional lines all messages longer than 512 characters are deleted automatically, though omegga wouldn’t have sent them anyway

whisper

whisper(target: string | OmeggaPlayer, ...messages: string[]): void

whisper messages to a player’s chat messages are broken by new line multiple arguments are additional lines all messages longer than 512 characters are deleted automatically, though omegga wouldn’t have sent them anyway

middlePrint

middlePrint(target: string | OmeggaPlayer, message: string): void

prints text to the middle of a player’s screen all messages longer than 512 characters are deleted automatically

saveMinigame

saveMinigame(index: number, name: string): void

Save a minigame preset based on a minigame index

deleteMinigame

deleteMinigame(index: number): void

Delete a minigame

resetMinigame

resetMinigame(index: number): void

Reset a minigame

nextRoundMinigame

nextRoundMinigame(index: number): void

Force the next round in a minigame

loadMinigame

loadMinigame(presetName: string, owner?: string): void

Load an Minigame preset

getMinigamePresets

getMinigamePresets(): string[]

Get all presets in the minigame folder and child folders

resetEnvironment

resetEnvironment(): void

Reset the environment settings

saveEnvironment

saveEnvironment(presetName: string): Promise<void>

Save an environment preset

getEnvironmentData

getEnvironmentData(): Promise<EnvironmentPreset | null>

Save a temporary environment preset and return its contents

readEnvironmentData

readEnvironmentData(presetName: string): EnvironmentPreset | null

Read environment data as json; null when the preset is missing or invalid

loadEnvironment

loadEnvironment(presetName: string): void

Load an environment preset

loadEnvironmentData

loadEnvironmentData(preset: | EnvironmentPreset | NonNullable<EnvironmentPreset['data']>['groups']): void

Load some environment preset data

getEnvironmentPresets

getEnvironmentPresets(): string[]

Get all presets in the environment folder and child folders

clearBricks

clearBricks(target: string | { id: string }, quiet?: boolean): void

Clear a user’s bricks (by uuid, name, controller, or player object)

clearRegion

clearRegion(region: { center: [number, number, number]; extent: [number, number, number]; }, options?: { target?: string | OmeggaPlayer; bricks?: boolean; entities?: boolean; }): void

Clear a region of bricks. On EA3 this routes to br.World.ClearRegion and can optionally clear entities too.

clearAllBricks

clearAllBricks(options?: | boolean | { quiet?: boolean; bricks?: boolean; entities?: boolean }): void

Clear all bricks on the server. On EA3 this routes to br.World.ClearAll and can optionally clear entities too. A bare boolean is accepted as the legacy quiet argument.

saveBricks

saveBricks(saveName: string, region?: { center: [number, number, number]; extent: [number, number, number]; }): void

Deprecated. removed in Brickadia EA3 (no-op on newer servers) - save a prefab with savePrefabRegion instead

Save bricks under a filename

saveBricksAsync

saveBricksAsync(saveName: string, region?: { center: [number, number, number]; extent: [number, number, number]; }): Promise<void>

Deprecated. removed in Brickadia EA3 (no-op on newer servers) - save a prefab with savePrefabRegion instead

Save bricks under a filename, with a promise

loadBricks

loadBricks(saveName: string, options?: { offX?: number; offY?: number; offZ?: number; quiet?: boolean; correctPalette?: boolean; correctCustom?: boolean; }): void

Deprecated. removed in Brickadia EA3 (no-op on newer servers) - load a prefab with loadPrefab instead

Load bricks on the server

loadBricksOnPlayer

loadBricksOnPlayer(saveName: string, player: string | OmeggaPlayer, options?: { offX?: number; offY?: number; offZ?: number; correctPalette?: boolean; correctCustom?: boolean; }): void

Deprecated. removed in Brickadia ~EA2 (no-op on newer servers) - use loadPrefabOnPlayer instead

Load bricks on the server into a player’s clipbaord

getSaves

getSaves(): string[]

Get all saves in the save folder and child folders

getSavePath

getSavePath(saveName: string): string | undefined

Checks if a save exists and returns an absolute path

Returns Path to string, undefined if the save does not exist

getWorlds

getWorlds(): string[]

Get all worlds in the worlds folder and child folders

getWorldPath

getWorldPath(worldName: string): string | undefined

Checks if a world exists and returns an absolute path

Returns Path to string, undefined if the world does not exist

getWorldRevisions

getWorldRevisions(worldName: string): Promise<{ index: number; date: Date; note: string }[]>

Get a list of revisions for a world

loadWorld

loadWorld(worldName: string): Promise<boolean>

Load a world by its name

loadWorldRevision

loadWorldRevision(worldName: string, revision: number): Promise<boolean>

Load a world at a specific revision

saveWorldAs

saveWorldAs(worldName: string): Promise<boolean>

Save a world as a new name

saveWorld

saveWorld(): Promise<boolean>

Save the current world

createEmptyWorld

createEmptyWorld(worldName: string): Promise<boolean>

Create an empty world with the given name

writeSaveData

writeSaveData(saveName: string, saveData: WriteSaveObject): void

unsafely load save data (wrap in try/catch)

readSaveData

readSaveData(saveName: string, nobricks?: boolean): ReadSaveObject

unsafely read save data (wrap in try/catch)

Returns BRS JS Save Data

loadSaveData

loadSaveData(saveData: WriteSaveObject, options?: { offX?: number; offY?: number; offZ?: number; quiet?: boolean; correctPalette?: boolean; correctCustom?: boolean; }): Promise<void>

Deprecated. removed in Brickadia EA3 (no-op on newer servers) - use the prefab API (loadPrefab) instead

load bricks from save data and resolve when game finishes loading

loadSaveDataOnPlayer

loadSaveDataOnPlayer(saveData: WriteSaveObject, player: string | OmeggaPlayer, options?: { offX?: number; offY?: number; offZ?: number; correctPalette?: boolean; correctCustom?: boolean; }): Promise<void>

Deprecated. removed in Brickadia ~EA2 (no-op on newer servers) - use the prefab API (loadPrefabOnPlayer) instead

load bricks from save data and resolve when game finishes loading

getSaveData

getSaveData(region?: { center: [number, number, number]; extent: [number, number, number]; }): Promise<ReadSaveObject | undefined>

Deprecated. removed in Brickadia EA3 (returns undefined on newer servers) - use the prefab API instead

get current bricks as save data

getPrefabs

getPrefabs(): string[]

Get all prefabs in the prefabs folder and child folders (EA3)

getPrefabPath

getPrefabPath(prefabName: string): string | undefined

Checks if a prefab exists and returns an absolute path (EA3)

Returns Path to string

loadPrefab

loadPrefab(path: string, options?: { offX?: number; offY?: number; offZ?: number; atOriginalPosition?: boolean; orientation?: number; rootEntityPersistentIndex?: number; mirrorAxes?: number; overrideUserId?: string; }): void

Load a prefab into the world (EA3). path is a bundle path ref such as Prefabs/Uploads/<hash>.brz.

savePrefab

savePrefab(path: string, options?: { region?: { center: [number, number, number]; extent: [number, number, number]; }; entities?: boolean; rootEntityPersistentIndex?: number; userId?: string; }): void

Save the world (or a region of it) as a prefab (EA3).

savePrefabAsync

savePrefabAsync(path: string, options?: { region?: { center: [number, number, number]; extent: [number, number, number]; }; entities?: boolean; rootEntityPersistentIndex?: number; userId?: string; }): Promise<string | null>

Save a prefab and resolve once the prefab file has been written to disk (EA3).

Returns absolute path to the written prefab, or null on timeout

givePrefabToPlayer

givePrefabToPlayer(path: string, player: string | OmeggaPlayer, options?: { preserveOwnership?: boolean }): void

Give a prefab to a player’s inventory (EA3).

loadPrefabOnPlayer

loadPrefabOnPlayer(path: string, player: string | OmeggaPlayer, options?: { preserveOwnership?: boolean }): void

Load a prefab onto a player (EA3, replaces loadBricksOnPlayer).

changeMap

changeMap(map: string): Promise<boolean>

Change server map

getRoleSetup

getRoleSetup(): BRRoleSetup

Get up-to-date role setup from RoleSetup.json

getRoleAssignments

getRoleAssignments(): BRRoleAssignments

Get up-to-date role assignments from RoleAssignment.json

getBanList

getBanList(): BRBanList

Get up-to-date ban list from BanList.json

getNameCache

getNameCache(): BRPlayerNameCache

Get up-to-date name cache from PlayerNameCache.json

_{Declared in src/plugin.ts.}

InjectedCommands

getServerStatus

getServerStatus(): Promise<IServerStatus | null>

Get server status

listMinigames

listMinigames(): Promise<IMinigameList>

Deprecated. minigames were replaced by a single gamemode (~CL14000); on modern servers this returns at most one entry with an empty owner. Prefer getGamemode.

Get a list of minigames and their indices

getAllPlayerPositions

getAllPlayerPositions(): Promise<IPlayerPositions>

Get all player positions and pawns

getMinigames

getMinigames(): Promise<ILogMinigame[]>

Get minigames and members (one entry per gamemode on modern servers)

getGamemode

getGamemode(): Promise<IGamemode | null>

Get the single gamemode and its teams/players (modern servers, >=CL14000). Returns null on older servers (use getMinigames).

_{Declared in src/plugin.ts.}

LogWrangling

addMatcher

addMatcher<T>(pattern: IMatcher<T>['pattern'], callback: IMatcher<T>['callback']): void

Add a passive pattern on console output that invokes callback on match

addWatcher

addWatcher<T = RegExpMatchArray>(pattern: IWatcher<T>['pattern'], options?: { timeoutDelay?: number; bundle?: boolean; debounce?: boolean; afterMatchDelay?: number; last?: IWatcher<T>['last']; exec?: () => void; }): Promise<T[]>

Run an active pattern on console output that resolves a match. T is the element type of the resolved matches - RegExpMatchArray for RegExp patterns, the pattern’s return type for function patterns.

watchLogChunk

watchLogChunk<T = RegExpMatchArray>(cmd: string, pattern: IWatcher<T>['pattern'], options?: { first?: 'index' | ((match: T) => boolean); last?: IWatcher<T>['last']; afterMatchDelay?: number; timeoutDelay?: number; }): Promise<T[]>

Run a command and capture bundled output. T is the element type of the resolved matches - RegExpMatchArray for RegExp patterns, the pattern’s return type for function patterns.

watchLogArray

watchLogArray<Item extends Record<string, string> = Record<string, string>, Member extends Record<string, string> = Record<string, string>>(cmd: string, itemPattern: RegExp, memberPattern: RegExp): Promise<{ item: Item; members: Member[] }[]>

Run a command and capture bundled output for array functions

_{Declared in src/plugin.ts.}