Block worlds

A world made of 1 m blocks that players dig and build in, generated from a seed. A platform feature: switch it on with EnableBlockWorld. Coordinates are whole blocks, which are the same as meters. Provided by the game (or gampeon-server).

EnableBlockWorld

EnableBlockWorld(options) --> boolean

Switch on the block world of this server. Server only.

Call it once when your resource starts, before players spawn. The world stays on until the server stops, also when your resource restarts; calling it again with the same options does nothing. Every client generates the same terrain from the seed, so only changed blocks travel over the network. With save, the server keeps changed blocks in a save file and loads them on the next start. Zones are flat areas without blocks for fixed buildings, for example a city: nobody can dig or build there, scripts neither.

Parameter	Type	Description
options	table	{ seed = integer, save = string?, zones = { { minX, minY, maxX, maxY, groundZ, blend?, floorZ? } }? }. seed: 0 to 4294967295. save: 1 to 32 characters a-z, 0-9, _ and -. Zone values are blocks; groundZ is the height of the fixed floor, blend (default 24) the width of the smooth edge, floorZ (default groundZ - 2) the top block of the hidden foundation inside the zone. Set floorZ lower to keep water or low ground of your own map visible. At most 8 zones.

Returns

• boolean: true when the world is on. Errors explain wrong options.

EnableBlockWorld({
  seed = 1337,
  save = 'main',
  zones = { { minX = -60, minY = -60, maxX = 60, maxY = 60, groundZ = 6 } },
})

IsBlockWorldEnabled

IsBlockWorldEnabled() --> boolean

Check whether this server has a block world. Server and client.

On clients it turns true once the world settings arrived from the server, shortly after joining.

Returns

• boolean: true when there is a block world.

GetBlockWorldSeed

GetBlockWorldSeed() --> integer|nil

Seed of the block world. Server only.

Returns

• integer|nil: The seed, nil without a block world.

GetBlock

GetBlock(x, y, z) --> string|nil

Block at a position. Server and client.

Works everywhere in the world, also far from players. GetBlock(GetEntityCoords(ped)) is the block the feet of a character are in.

Parameter	Type	Description
x	number	Block x (or a vector3 here and leave out y and z). Decimals are rounded down.
y	number	Block y.
z	number	Block z, up.

Returns

• string|nil: Block name such as “stone” or “air”, nil without a block world.

local pos = GetEntityCoords(GetPlayerPed(source))
if GetBlock(pos.x, pos.y, pos.z - 1) == 'sand' then
  print('on the beach')
end

SetBlock

SetBlock(x, y, z, block) --> boolean

Change a block for every player. Server only.

Scripts may set any block, including ones players cannot place. Fires blockChanged. Changes inside zones, outside the world and on the bottom layer are refused.

Parameter	Type	Description
x	number	Block x (or a vector3 here and leave out y and z). Decimals are rounded down.
y	number	Block y.
z	number	Block z, up.
block	string	Block name, see GetBlockTypes. “air” removes the block.

Returns

• boolean: false if the position is protected or outside the world.

-- a small tower of bricks
for z = 10, 14 do
  SetBlock(20, 30, z, 'brick')
end

GetBlockSurfaceZ

GetBlockSurfaceZ(x, y) --> integer|nil

Height of the highest solid block in a column. Server and client.

Parameter	Type	Description
x	number	Block x (or a vector2/vector3 here and leave out y).
y	number	Block y.

Returns

• integer|nil: z of the top solid block, nil without a block world. Its top face is at z + 1, so a character stands there with its middle at about z + 2.

local z = GetBlockSurfaceZ(100, 100)
SetEntityCoords(GetPlayerPed(source), 100.5, 100.5, z + 2.0)

IsBlockProtected

IsBlockProtected(x, y, z) --> boolean

Check whether a position is inside a zone or outside the world, where nobody can change blocks. Server and client.

Parameter	Type	Description
x	number	Block x (or a vector3 here and leave out y and z). Decimals are rounded down.
y	number	Block y.
z	number	Block z, up.

Returns

• boolean: true where blocks cannot change.

GetBlockTypes

GetBlockTypes() --> table

All block types. Server and client.

The list only grows. Blocks with breakable = false (deepstone) cannot be dug by players; placeable = false means players cannot place them (ores), but scripts can.

Returns

• table: List of { id = ‘stone’, name = ‘Stone’, solid = true, breakable = true, placeable = true }, without air.

GetBlockTarget

GetBlockTarget() --> integer|nil, integer, integer, integer, integer, integer

Block under the crosshair within reach. Client only.

Returns

• integer|nil: x of the block, nil when the crosshair points at nothing within reach.
• integer: y
• integer: z
• integer: nx: side the crosshair points at (-1, 0 or 1). Placing puts the new block at x + nx.
• integer: ny
• integer: nz

local x, y, z = GetBlockTarget()
if x then
  print('looking at ' .. GetBlock(x, y, z))
end

SetBlockHotbar

SetBlockHotbar(slots)

Blocks the player can place, in the slots of the hotbar. Client only.

The player picks a slot with the mouse wheel or keys 1 to 9 and places it with the right mouse button. An empty list switches placing off. Send the list from your server inventory with an event; the server still asks blockPlace before anything changes.

Parameter	Type	Description
slots	table	Up to 9 entries: a block name, or { block = ‘planks’, count = 12 } to show a number.

RegisterNetEvent('mygame:inventory', function(items)
  SetBlockHotbar(items) -- { { block = 'stone', count = 32 }, ... }
end)

GetBlockHotbarSlot

GetBlockHotbarSlot() --> integer

Selected slot of the hotbar. Client only.

Returns

• integer: Slot from 1, 0 when the hotbar is empty.

SetBlockControlsEnabled

SetBlockControlsEnabled(enabled)

Turn digging and placing with the mouse on or off for this player. Client only.

On by default. Turn it off while a menu is open or in areas where your game does not allow building.

Parameter	Type	Description
enabled	boolean	false turns the controls off.

SetBlockHudVisible

SetBlockHudVisible(visible)

Show or hide the built-in crosshair, block outline and hotbar. Client only.

Hide it when your resource draws its own hotbar with a web interface (NUI). The controls keep working.

Parameter	Type	Description
visible	boolean	false hides it.