entities - GregHib/void GitHub Wiki

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:

Screenshot 2024-02-20 171650

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") {
}
⚠️ **GitHub.com Fallback** ⚠️