Entities

Entity is a broad category for everything that exists in the game world, with a second sub-category Character for Player and NPC entities that can move. The main Entity types are:

• Blue - Players
• Green - NPCs (Non-Player Characters)
• Orange - Objects (GameObjects)
• Purple - Floor items

Note

Item's are considered a part of interfaces not entities, for more info see Inventories.

Players

Players are the characters controlled by people, they are used to explore the world, interact with other entities, and hold information about what they have collected and accomplished so far.

Player Data includes:

Data	Description
Account name	The username used to log into the game.
Password hash	Encrypted value used to verify a correct password.
Index	The number between 1-2048 a particular player is in the current game world.
Tile	The current position of the player represented as an x, y, level coordinate.
Inventory	Various stores of Items from equipment to shops.
Variables	Progress and tracking data for all types of content.
Experience	Progress gained in skilling towards a Level.
Levels	Boundaries of skilling experience which unlock new content.
Friends	List of befriended players that can be messaged directly.
Ignores	List of players who's messages will be hidden.
Client	The network connection between the persons Game Client and the game server.
Viewport	A store of the entities in the visibile surrounding area.
Body	The players appearance with/without equipment.
Mode	The players current style of movement.
Visuals	The players general appearance.
Instructions	Instructions send by the Client or Bot controller.
Options	Possible interactions other entities can have with this player.
Interfaces	All the Interfaces the player's Client currently has opened.
Collision	Strategy for how the player can move about the game world.
ActionQueue	List of Queues currently in progress for the player.
Soft Timer	Timers that are always counting down for the player.
Timers	Pausable Timers that are counting down for the player.
Steps	List of tiles the player plans on walking to in the future.

Bots

As Void is not currently hosted online and have other people playing it supplements players with a number of bot controlled players to make the world feel more alive and active even when playing offline and locally.

Finding players

Most code used throughout the game will already have access to the Player in question, in the situations where one player needs to find or reference another player they can be searched for in the worlds list of Players.

The Players list can be accessed from any script using:

val players: Players by inject()

Or from any function using:

val players: Players = get()

You can search for a player by name, index, Tile or Zone:

val player = players.get(42) // Get player at an index

val player = players.get("Cow31337Killer") // Get a specific player by name

val playersUnder = players[Tile(3200, 3200)] // Get all players under a tile

val playersNearby = players[Zone(402, 403)] // Get all players in 8x8 area

Adding players

There should be no need to add new players as it is already handled by the LoginServer, if you do happen to need access, see PlayerAccountLoader.

You can subscribe to new players being spawned with:

playerSpawn { player ->
    player.message("Welcome to Void.", ChatType.Welcome)
}

Removing players

Again for most situations removing players is already handled, player.logout() is enough for other scenarios.

You can subscribe to removed players with:

playerDespawn { player ->
    player.cancelQuickPrayers()
}

Player options

Scripts can subscribe to player options with:

playerOperate("Req Assist") {
}

Tip

See interactions for more info including the difference between operate and approach interactions.

NPCs

NPCs are characters in the game for Players to interact with, talk to for quests, information or shops, and fight in combat although these are typically referred to as Monsters.

While NPCs have a lot of similarities with Players as both are Characters, NPCs have a lot less data:

Data	Description
Id	The type of npc as a String identifier.
Index	The number between 1-32768 a particular npc is in the current game world.
Tile	The current position of the npc represented as an x, y, level coordinate.
Levels	Fixed levels used in Combat calculations.
Mode	The npcs current style of movement.
Definition	Definition data about this particular type of npc.
ActionQueue	List of Queues currently in progress for the npc.
Soft Timer	The one Timer that is currently counting down for the npc.
Variables	Progress and tracking data for different types of content.
Steps	List of tiles the player plans on walking to in the future.
Collision	Strategy for how the npc can move about the game world.
Visuals	The npcs general appearance.

Finding NPCs

Much like Players NPCs can be found using the world NPCs list which can be access from scripts with:

val npcs: NPCs by inject()

Or in functions with:

val npcs: NPCs = get()

And the also can be searched for by id, index, Tile or Zone:

val npc = npcs.get(42) // Get npc at an index

val npc = npcs.get("chicken") // Get a specific npc by id

val npcsUnder = npcs[Tile(3200, 3200)] // Get all npcs under a tile

val npcsNearby = npcs[Zone(402, 403)] // Get all npcs in 8x8 area

Adding NPCs

One off npc spawns can be added using NPCs:

val cow = npcs.add("cow_brown", Tile(3200, 3200), Direction.NORTH)

Where permanent npcs and respawning monsters should be added to /data/spawns/npc-spawns.yml

- { id: cow_brown, x: 2921, y: 3287 }

Scripts can subscribe to npc spawns with:

npcSpawn("cow*") { npc ->
    npc.softTimers.start("eat_grass")
}

Removing NPCs

NPCs can be removed easily with:

npcs.remove(cow)

And Scripts can subscribe to despawns using:

npcDespawn { npc ->
    npc.softTimers.stopAll()
}

NPC options

NPC interactions can be subscribed to as well:

npcApproach("Talk-to", "banker*") {
}
npcOperate("Talk-to", "zeke") {
}

Tip

See interactions for more info including the difference between operate and approach interactions.

Game Objects

Game objects make up the entire game world from scenery rocks on the floor, to castle walls and trees there are over 3.5 million game objects across the world. The majority of objects are inactive and never change, other objects are active and can be interacted with by Players.

Due to the shear number of objects in the world they are stored with little information compared to other entities, a game object stores:

Data	Description
Id	The type of object as a String identifier.
Tile	The position of the object as an x, y, level coordinate.
Definition	Definition data about this particular type of object.
Shape	The type of object, used for layering and interaction path finding.
Rotation	A number between 0-3 which represents the direction the object is facing.

Objects are all stored in the GameObjects map which can be access from scripts with:

val objects: GameObjects by inject()

Or in functions with:

val objects: GameObjects = get()

Finding objects

The GameObjects map can be searched by Tile and id, layer or shape:

val tile = Tile(3200, 3200)
val objectsUnder = objects.get(tile) // Get all objects on a tile

val gameObject = objects.get(tile, "large_door_opened") // Get specific object by id

val gameObject = objects.getShape(tile, ObjectShape.WALL_CORNER) // Get specific object by shape

val gameObject = objects.getLayer(tile, ObjectLayer.WALL_DECORATION) // Get specific object by layer

Adding objects

New objects can be spawned with GameObjects add() function allowing scripts to modify the world at any time

// Temporarily add a fire for 60 ticks
val obj = objects.add("fire", tile, shape = ObjectShape.CENTRE_PIECE_STRAIGHT, rotation = 0, ticks = 60)

Warning

Adding a object will override existing objects with the same ObjectLayer.

Permanent changes should be added to /data/spawns/object-spawns.yaml to be spawned every time the world loads:

- { id: crate, x: 3081, y: 3488, type: 10, rotation: 1 }

Removing objects

Objects can also be removed temporarily or permanently

objectOperate("Pick", "wheat") {
    target.remove(30) // Remove the object for 30 ticks
    player.message("You pick some wheat.")
}

Replacing objects

One object can also be replaced with another temporarily or permanently

objectOperate("Slash", "web*") {
    player.setAnimation("dagger_slash")
    target.replace("web_slashed", ticks = TimeUnit.MINUTES.toTicks(1)) // Replace the object for 100 ticks
}

Floor Items

Floor items are items that are either spawned with item-spawns.yml, dropped by Monsters or by other Players. They can be picked up to move them into a Players Inventory.

An item that is dropped will only be shown to the person it was dropped by/for and after revealTicks it will be shown to all Players, disappearTicks after that it will be permanently deleted from the world.

Data	Description
Id	The type of item as a String identifier.
Amount	The amount of the item in this stack.
Definition	Definition data about this particular type of item.
Tile	The position of the item represented as an x, y, level coordinate.
Reveal ticks	Number of ticks before an item is made public for everyone.
Disappear ticks	Number of ticks before the item is permanently deleted.
Owner	The original owner of the item.

Much the same as other entities, FloorItems contains and can be used to control all the floor items in the world, it can be accessed from scripts with:

val floorItems: FloorItems by inject()

Or in functions with:

val floorItems: FloorItems = get()

Find floor items

Floor items can be found searched for by Tile or Zone:

val itemsUnder = floorItems[Tile(3200, 3200)] // Get all items on a tile

val itemsNearby = floorItems[Zone(402, 403)] // Get all items in 8x8 area

Adding floor items

Items can be spawned onto the floor with:

val floorItem = floorItems.add(tile, "ashes", revealTicks = 90, disappearTicks = 60)

Reoccuring floor items should be added to /data/spawns/item-spawns.yml:

- { id: spade, x: 1951, y: 4964, delay: 100, members: true }

Removing floor items

Floor items can also be removed with:

npcFloorItemOperate("Take") {
    floorItems.remove(target)
}

World

Although only an entity due to technicality the World also has a number of operations the same as other entities.

World spawn and despawn are called on server startup and shutdown:

worldSpawn {
}

worldDespawn {
}

And world timers work the same as other entities:

worldTimerStart("timer_name") {
}
worldTimerTick("timer_name") {
}
worldTimerStop("timer_name") {
}