Options
All
  • Public
  • Public/Protected
  • All
Menu

Class GameWorld

The game world. Contains all global methods of the API. You don't create an instance of this class directly, instead use the world object that always exists.

Hierarchy

  • GameWorld

Index

Methods

addDrawingLine

addUI

  • Add a new global UI element in the world

    Parameters

    Returns number

    • The index of the added UI element

boxOverlap

  • boxOverlap(position: Vector | [x: number, y: number, z: number], extent: Vector | [x: number, y: number, z: number], orientation?: Rotator | [pitch: number, yaw: number, roll: number]): GameObject[]
  • Find all objects that would collide with a box

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      Center of the box

    • extent: Vector | [x: number, y: number, z: number]

      Dimensions of the box (from center to on of the corners)

    • Optional orientation: Rotator | [pitch: number, yaw: number, roll: number]

      Orientation of the box

    Returns GameObject[]

boxTrace

  • boxTrace(start: Vector | [x: number, y: number, z: number], end: Vector | [x: number, y: number, z: number], extent: Vector | [x: number, y: number, z: number], orientation?: Rotator | [pitch: number, yaw: number, roll: number]): TraceHit[]
  • Find all object hits with a box that is moved along a line, ordered by distance to start

    Parameters

    • start: Vector | [x: number, y: number, z: number]

      Starting point of the box

    • end: Vector | [x: number, y: number, z: number]

      End point of box movement

    • extent: Vector | [x: number, y: number, z: number]

      Dimensions of the box (from center to on of the corners)

    • Optional orientation: Rotator | [pitch: number, yaw: number, roll: number]

      Orientation of the box

    Returns TraceHit[]

broadcastChatMessage

  • broadcastChatMessage(message: string, color?: Color | [r: number, g: number, b: number, a: number]): void
  • Send a chat message to all players

    Parameters

    • message: string
    • Optional color: Color | [r: number, g: number, b: number, a: number]

    Returns void

capsuleOverlap

  • capsuleOverlap(position: Vector | [x: number, y: number, z: number], extent: Vector | [x: number, y: number, z: number], orientation?: Rotator | [pitch: number, yaw: number, roll: number]): GameObject[]
  • Find all objects that would collide with a capsule

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      Center of the capsule

    • extent: Vector | [x: number, y: number, z: number]

      Dimensions of the capsule (from center to one of the corners of the surrounding box)

    • Optional orientation: Rotator | [pitch: number, yaw: number, roll: number]

      Orientation of the capsule

    Returns GameObject[]

capsuleTrace

  • capsuleTrace(start: Vector | [x: number, y: number, z: number], end: Vector | [x: number, y: number, z: number], extent: Vector | [x: number, y: number, z: number], orientation?: Rotator | [pitch: number, yaw: number, roll: number]): TraceHit[]
  • Find all objects hits with a capsule that is moved along a line, ordered by distance to start

    Parameters

    • start: Vector | [x: number, y: number, z: number]

      Starting point of the capsule

    • end: Vector | [x: number, y: number, z: number]

      End point of the capsule movement

    • extent: Vector | [x: number, y: number, z: number]

      Dimensions of the capsule

    • Optional orientation: Rotator | [pitch: number, yaw: number, roll: number]

      Orientation of the capsule

    Returns TraceHit[]

clearConsole

  • clearConsole(): void
  • Clear the built-in JavaScript console. The same effect can be achieved by entering "clear()" in the console.

    Returns void

createObjectFromJSON

  • createObjectFromJSON(jsonString: string, position: Vector | [x: number, y: number, z: number]): GameObject | undefined
  • Create a new object from a JSON string

    Parameters

    • jsonString: string

      String containing Json representation of an object (can be obtained by calling toJSONString() on an object)

    • position: Vector | [x: number, y: number, z: number]

      Starting position

    Returns GameObject | undefined

createObjectFromTemplate

  • createObjectFromTemplate(templateId: string, position: Vector | [x: number, y: number, z: number]): GameObject | undefined
  • Create a new object from a template

    Parameters

    • templateId: string

      Template GUID for the new object

    • position: Vector | [x: number, y: number, z: number]

      Starting position

    Returns GameObject | undefined

createZone

  • createZone(position: Vector | [x: number, y: number, z: number]): Zone
  • Create a new zone with default parameters and 1cm edge length

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      The position of the new zone

    Returns Zone

drawDebugBox

  • drawDebugBox(center: Vector | [x: number, y: number, z: number], extent: Vector | [x: number, y: number, z: number], orientation: Rotator | [pitch: number, yaw: number, roll: number], color: Color | [r: number, g: number, b: number, a: number], duration: number, thickness?: number): void
  • Draw a box in 3d space. The box will only be visible on for the host!

    Parameters

    • center: Vector | [x: number, y: number, z: number]

      The center of the box

    • extent: Vector | [x: number, y: number, z: number]

      Maximum point of the box

    • orientation: Rotator | [pitch: number, yaw: number, roll: number]

      The rotation of the box

    • color: Color | [r: number, g: number, b: number, a: number]

      Color of the box. Alpha value is not used.

    • duration: number

      Amount of time in seconds to show the box. Can be 0 to show for one frame only.

    • Optional thickness: number

      Thickness of the lines. One pixel thick if 0, cm thickness for values > 0.

    Returns void

drawDebugLine

  • drawDebugLine(start: Vector | [x: number, y: number, z: number], end: Vector | [x: number, y: number, z: number], color: Color | [r: number, g: number, b: number, a: number], duration: number, thickness?: number): void
  • Draw a line in 3d space. The line will only be visible on for the host!

    Parameters

    • start: Vector | [x: number, y: number, z: number]

      Starting point of the line

    • end: Vector | [x: number, y: number, z: number]

      End point of the line

    • color: Color | [r: number, g: number, b: number, a: number]

      Color of the line. Alpha value is not used.

    • duration: number

      Amount of time in seconds to show the line. Can be 0 to show for one frame only

    • Optional thickness: number

      Thickness of the line. One pixel thick if 0, cm thickness for values > 0.

    Returns void

drawDebugPoint

  • drawDebugPoint(position: Vector | [x: number, y: number, z: number], size: number, color: Color | [r: number, g: number, b: number, a: number], duration: number): void
  • Draw a point. The point will only be visible on for the host!

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      Position of the point

    • size: number

      Size of the point in cm

    • color: Color | [r: number, g: number, b: number, a: number]

      Color of the point. Alpha value is not used.

    • duration: number

      Amount of time in seconds to show the point. Can be 0 to show for one frame only.

    Returns void

drawDebugSphere

  • drawDebugSphere(position: Vector | [x: number, y: number, z: number], radius: number, color: Color | [r: number, g: number, b: number, a: number], duration: number, thickness?: number): void
  • Draw a point. The sphere will only be visible on for the host!

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      Position of the point

    • radius: number
    • color: Color | [r: number, g: number, b: number, a: number]

      Color of the sphere. Alpha value is not used.

    • duration: number

      Amount of time in seconds to show the point. Can be 0 to show for one frame only.

    • Optional thickness: number

      Thickness of the lines. One pixel thick if 0, cm thickness for values > 0.

    Returns void

getAllObjects

  • getAllObjects(skipContained?: boolean): GameObject[]
  • Return all objects currently in the game

    Parameters

    • Optional skipContained: boolean

      If true, don't return objects in containers. Even when false, objects within lazy containers that haven't been loaded yet will never be returned. Use Container.getItems to load and return items in lazy containers. Default: false

    Returns GameObject[]

getAllPlayers

getAllZones

  • getAllZones(): Zone[]

getAllowedPackages

getBackgroundFilename

  • getBackgroundFilename(): string
  • Return the filename of the current background. Empty string if no custom background is active.

    Returns string

getBackgroundPackageId

  • getBackgroundPackageId(): string
  • Return the package id of the current background. Returns an empty string if no background is set.

    Returns string

getCurrentTurn

  • getCurrentTurn(): number

getDrawingLines

getGameTime

  • getGameTime(): number
  • Return the time in seconds since the game session was started

    Returns number

getGravityMultiplier

  • getGravityMultiplier(): number
  • Return the current gravity multiplier

    Returns number

getObjectById

  • getObjectById(objectId: string): GameObject | undefined
  • Return the game object with the specified Id

    Parameters

    • objectId: string

      The unique id of the object

    Returns GameObject | undefined

getObjectGroupIds

  • getObjectGroupIds(): number[]
  • Return an array of all currently used object group ids. Objects with the same group id are always picked up together.

    Returns number[]

getObjectsByGroupId

  • getObjectsByGroupId(groupId: number): GameObject[]
  • Return an array of all objects with a given object group id.

    Parameters

    • groupId: number

      The group id to query

    Returns GameObject[]

getObjectsByTemplateId

  • getObjectsByTemplateId(templateId: string): GameObject[]
  • Return all objects in the game with the specified template type

    Parameters

    • templateId: string

      The template id to search for

    Returns GameObject[]

getPackageById

  • getPackageById(packageId: string): Package | undefined
  • Return the package with the specified id. Can return packages that are currently not allowed, but only finds packages that exist on the host.

    Parameters

    • packageId: string

    Returns Package | undefined

getPlayerBySlot

  • getPlayerBySlot(slot: number): Player | undefined
  • Return the player occupying the specified slot

    Parameters

    • slot: number

      The player slot (0-19)

    Returns Player | undefined

getSavedData

  • getSavedData(key?: string): string
  • Return data that was stored using setSavedData or loaded from a saved state.

    Parameters

    • Optional key: string

      Key for which to retrieve the data.

    Returns string

getShowDiceRollMessages

  • getShowDiceRollMessages(show: boolean): boolean
  • Return whether a message with results is shown whenever rolled dice come to rest

    Parameters

    • show: boolean

    Returns boolean

getSlotColor

  • getSlotColor(slot: number): Color
  • Return the color of a player slot.

    Parameters

    • slot: number

      The player slot (0-19)

    Returns Color

getSlotTeam

  • getSlotTeam(slot: number): number
  • Return the team (1-8) of a player slot. Returns 0 if the player slot is not associated to a team.

    Parameters

    • slot: number

      The player slot (0-19)

    Returns number

getTableHeight

  • getTableHeight(position?: Vector | [x: number, y: number, z: number]): number
  • Return the Z coordinate of the table at a given point. Returns 0 if the point is outside of the table bounds. For many tables this will return the same values for the entire surface, but some tables (like the included Poker table) have more complex surface geometry.

    Parameters

    • Optional position: Vector | [x: number, y: number, z: number]

      The point where the table height should be evaluated. The Z coordinate of the Vector is ignored. Returns table height for the center of the map (0,0) if this parameter is not given.

    Returns number

getTemplateName

  • getTemplateName(templateId: string): string
  • Return the name of a template

    Parameters

    • templateId: string

    Returns string

getTemplatePackageId

  • getTemplatePackageId(templateId: string): string
  • Return the package id of a template

    Parameters

    • templateId: string

    Returns string

getUIs

getZoneById

  • getZoneById(zoneId: string): Zone | undefined
  • Return the zone with the specified id

    Parameters

    • zoneId: string

    Returns Zone | undefined

importSound

  • importSound(filename: string, packageId?: string, ignoreCache?: boolean): Sound
  • Load a sound file from the Sounds folder of a package and store it in a sound object that can be played. Supports WAV, MP3, and FLAC files.

    Parameters

    • filename: string

      The filename of the sound

    • Optional packageId: string

      The id of the package that contains the sound file (in the Sounds folder). Can usually be empty when used from scripts to use the same package that contains the script file, but you need to explicitly pass refPackageId for the current package or a package id when you use it in a callback. You can find package ids in the manifest.json file in package folders. Usually you won't use this parameter, unless you have a specific reason to load a sound from a different package than where the script is located.

    • Optional ignoreCache: boolean

      If true, load a new Sound even if a cached version already exists. Will take longer and take additional resources, only use if you need to play the same sound file multiple times at the same time. Default: false

    Returns Sound

importSoundFromURL

  • importSoundFromURL(url: string, ignoreCache?: boolean): Sound
  • Load a sound file from a web URL and store it in a sound object that can be played. Supports WAV, MP3, and FLAC files.

    Parameters

    • url: string

      The URL from which to load the sound

    • Optional ignoreCache: boolean

      If true, load a new Sound even if a cached version already exists. Will take longer and take additional resources, only use if you need to play the same sound file multiple times at the same time. Default: false

    Returns Sound

importText

  • importText(filename: string, packageId?: string): string
  • Load a text file from the Scripts folder of a package and return the text as string.

    Parameters

    • filename: string

      The filename of the text file

    • Optional packageId: string

      The id of the package that contains the text file (in the Scripts folder). Can usually be empty when used from scripts to use the same package that contains the script file, but you need to explicitly pass refPackageId for the current package or a package id when you use it in a callback. You can find package ids in the manifest.json file in package folders. Usually you won't use this parameter, unless you have a specific reason to load a text file from a different package than where the script is located.

    Returns string

lineTrace

  • lineTrace(start: Vector | [x: number, y: number, z: number], end: Vector | [x: number, y: number, z: number]): TraceHit[]
  • Find all object hits on the given line, ordered by distance to start

    Parameters

    • start: Vector | [x: number, y: number, z: number]

      Starting point of the line

    • end: Vector | [x: number, y: number, z: number]

      End point of the line

    Returns TraceHit[]

nextTurn

  • nextTurn(): void

previousTurn

  • previousTurn(): void

removeDrawingLine

  • removeDrawingLine(index: number): void
  • Remove a drawn line from the object.

    Parameters

    • index: number

    Returns void

removeUI

  • removeUI(index: number): void
  • Remove a global UI element.

    Parameters

    • index: number

      The index of the UI element to remove

    Returns void

removeUIElement

resetScripting

  • resetScripting(): void
  • Reset scripting environment and reload all scripts

    Returns void

setBackground

  • setBackground(textureName?: string, packageId?: string): void
  • Set the image shown as background of the map.

    Parameters

    • Optional textureName: string

      The filename of the image to load. Use an empty string to return to the default background for the map. Default: empty string.

    • Optional packageId: string

      The id of the package that contains the image file (in the Textures folder). Can usually be empty when used from scripts to use the same package that contains the script file, but you need to explicitly pass refPackageId for the current package or a package id when you use it in a callback. You can find package ids in the manifest.json file in package folders. Usually you won't use this parameter, unless you have a specific reason to load an image from a different package than where the script is located.

    Returns void

setGravityMultiplier

  • setGravityMultiplier(multiplier: number): void
  • Set the gravity multiplier. 1 is standard gravity, 0 will disable gravity. Wakes up physics simulation for all objects that are not locked (for example because they are ground objects, or because the locked physics option is active)

    Parameters

    • multiplier: number

      The new gravity multiplier, between 0 and 2

    Returns void

setSavedData

  • setSavedData(data: string, key?: string): void
  • Set the data that will stored in save game states. The data is available using getSavedData when the global script is run after loading a save state. Try to keep this data small and don't change it frequently, it needs to be sent over the network to all clients. A similar method exists for each game object: GameObject.setSavedData.
    If you want to use custom data that is not a string, you can encode it to JSON using JSON.stringify(), and then decode what you get from getSavedData using JSON.parse().

    Parameters

    • data: string

      Data to store, maximum length 1023 characters

    • Optional key: string

      Key for the data. This works like a dictionary, you can store different data for each key

    Returns void

setShowDiceRollMessages

  • setShowDiceRollMessages(show: boolean): void
  • Set whether a message with results is shown whenever rolled dice come to rest

    Parameters

    • show: boolean

    Returns void

setSlotColor

  • setSlotColor(slot: number, color: Color | [r: number, g: number, b: number, a: number]): void
  • Set the color of a player slot

    Parameters

    • slot: number

      The player slot (0-19)

    • color: Color | [r: number, g: number, b: number, a: number]

    Returns void

setSlotTeam

  • setSlotTeam(slot: number, team: number): void
  • Set the team of a player slot

    Parameters

    • slot: number

      The player slot (0-19)

    • team: number

      The new team for the slot. Use 0 to not associate the slot with a team.

    Returns void

setUI

  • setUI(index: number, element: UIElement): void
  • Replace a global UI element. Will not do anything if called with an index that doesn't have a UI element.

    Parameters

    Returns void

showPing

  • showPing(position: Vector | [x: number, y: number, z: number], color: Color | [r: number, g: number, b: number, a: number], playSound: boolean): void
  • Show a ping for all players, similar to when a player places a ping.

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      The position to ping

    • color: Color | [r: number, g: number, b: number, a: number]

      The color of the ping

    • playSound: boolean

      If true, the ping sound will be played for all players

    Returns void

sphereOverlap

  • sphereOverlap(position: Vector | [x: number, y: number, z: number], radius: number): GameObject[]
  • Find all objects that would collide with a sphere

    Parameters

    • position: Vector | [x: number, y: number, z: number]

      Center of the sphere

    • radius: number

      Radius of the sphere

    Returns GameObject[]

sphereTrace

  • sphereTrace(start: Vector | [x: number, y: number, z: number], end: Vector | [x: number, y: number, z: number], radius: number): TraceHit[]
  • Find all objects hits with a sphere that is moved along a line, ordered by distance to start

    Parameters

    • start: Vector | [x: number, y: number, z: number]

      Starting point of the sphere

    • end: Vector | [x: number, y: number, z: number]

      End point of the sphere movement

    • radius: number

      Radius of the sphere

    Returns TraceHit[]

startDebugMode

  • startDebugMode(port?: number): void
  • Start debug mode on the given port. You can use the Chrome DevTools or the Visual Studio Code debugger to connect to the specified port and debug your scripts.
    For example, with port 9229 (the default), open the following URL to open the DevTools: devtools://devtools/bundled/inspector.html?v8only=true&ws=localhost:9229
    For Visual Studio Code, add the following to your debug configurations:

    {
      "name": "Inspector",
          "type": "node",
          "protocol": "inspector",
          "request": "attach",
          "address": "localhost",
          "port": 9229
    }

    Parameters

    • Optional port: number

    Returns void

updateUI

  • Update a global UI element. Will not do anything if called with a UI element that is not currently part of the global UI elements.

    Parameters

    Returns void

Static getExecutionReason

  • getExecutionReason(): string
  • Used while executing the global script to determine why it was executed. Possible return values:
    "ScriptReload" - The script was reloaded, for example because it was set in the session options, or because the scripting environment was reset
    "StateLoad" - A game state that has the script set as global script was loaded
    "" - If called at other times

    Returns string