Project wiki moved to doc folder + english translation (#182)
This commit is contained in:
MihailRis
@@ -0,0 +1,11 @@
|
||||
# Sections
|
||||
|
||||
- [Engine usage recommendations](1.Engine-usage-recommendations.md)
|
||||
- [Content-packs](2.Content-packs.md)
|
||||
- [Block properties](3.Block-properties.md)
|
||||
- [Item properties](4.Item-properties.md)
|
||||
- [XML UI building](5.XML-UI-building.md)
|
||||
- [Assets preloading](6.Assets-preloading.md)
|
||||
- [Audio](7.Audio.md)
|
||||
- [Scripting](8.Scripting.md)
|
||||
- [Block modoels](9.Block-models.md)
|
||||
@@ -0,0 +1,31 @@
|
||||
# Engine usage recommendations
|
||||
|
||||
## Content naming
|
||||
|
||||
### Content packs ID
|
||||
|
||||
Content pack identifier requirements:
|
||||
- name can consist of Capital letters A-Z, lowercase letters a-z digits 0-9, and underscore '\_' signs.
|
||||
- the first character must not be a digit.
|
||||
- name length must be in range \[2, 24\]
|
||||
|
||||
### Blocks and items
|
||||
|
||||
- blocks and items identifiers follow the same requirements as content-pack ID.
|
||||
- `.item` suffix added only to replace auto-generated block item. Example: `base:stone.item` - an item generated for stone block.
|
||||
- **caption** field specifying name displayed in inventory UI should not be Capitalized. The engine does it automatically depending on display context.
|
||||
|
||||
## Storage
|
||||
|
||||
### Content packs data
|
||||
|
||||
Settings and other state that supposed to be saved with a world, must be stored in `world:data/pack_id/`. The path should be retrieved by calling a function:
|
||||
```lua
|
||||
local path = pack.data_file(PACK_ID, "file_name")
|
||||
file.write(path, some_data)
|
||||
-- writes data to file world:data/PACK_ID/file_name
|
||||
```
|
||||
PACK_ID is an existing variable containing current content-pack name.
|
||||
|
||||
Directory `world:data/PACK_ID` will be created on call `pack.data_file(...)`.
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# Content-packs
|
||||
|
||||
Every content pack must have an ID following requirements:
|
||||
- name can consist of Capital letters A-Z, lowercase letters a-z digits 0-9, and underscore '\_' signs.
|
||||
- the first character must not be a digit.
|
||||
- name length must be in range \[2, 24\]
|
||||
|
||||
Content-pack folder having name same as ID may be created in *res/content*.
|
||||
Content-pack folder must contain file **package.json** with following contents:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "pack_id",
|
||||
"title": "pack name will be displayed in the content menu",
|
||||
"version": "content-pack version - major.minor",
|
||||
"creator": "content-pack creator",
|
||||
"description": "short description",
|
||||
"dependencies": [
|
||||
"pack",
|
||||
"dependencies"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"id": "doors",
|
||||
"title": "DOORS",
|
||||
"creator": "MihailRis",
|
||||
"version": "1.0",
|
||||
"description": "doors test"
|
||||
}
|
||||
```
|
||||
|
||||
Content pack picture should be added as *icon.png* file. Recommended size: 128x128
|
||||
|
||||
See *res/content/base* as an example of content pack structure.
|
||||
|
||||
|
||||
@@ -0,0 +1,130 @@
|
||||
# Block properties
|
||||
## Visual
|
||||
|
||||
### *texture*
|
||||
|
||||
Block texture name (name of the file in `textures/blocks/` with no path and extension included, just name)
|
||||
|
||||
Texture file must be a **png** image
|
||||
|
||||
### *texture-faces*
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Can't be used if `texture` already specified
|
||||
|
||||
An array of 6 texture names for block sides.
|
||||
|
||||
Example:
|
||||
```json
|
||||
"texture-faces": [
|
||||
"grass_side",
|
||||
"grass_side",
|
||||
"dirt",
|
||||
"grass_top",
|
||||
"grass_side",
|
||||
"grass_side"
|
||||
]
|
||||
```
|
||||
|
||||
### *model*
|
||||
|
||||
Block model type from list:
|
||||
- "block" - default block model
|
||||
- "none" - invisible block (air)
|
||||
- "X" - grass model (two crossed sprites)
|
||||
- "aabb" - model based of block hitbox (complex hitbox will be combined into one). Examples: pipes, bulbs, panels.
|
||||
|
||||
### *draw-group*
|
||||
|
||||
Integer specifying number of block draw group (render order). Used for semi-transparent blocks.
|
||||
|
||||
### *rotation*
|
||||
|
||||
Rotation profile (set of available block rotations and behaviour of placing block rotation) from list:
|
||||
|
||||
- "none" - no rotation available (default profile)
|
||||
- "pipe" - wood logs, pipes, pillars
|
||||
- "pane" - panels, doors, signs
|
||||
|
||||
## Lighting
|
||||
|
||||
### *emission*
|
||||
|
||||
An array of 3 integers - R, G, B of light in range \[0, 15\]
|
||||
|
||||
Examples:
|
||||
|
||||
- *\[15, 15, 15\]* - white with maximal intensity
|
||||
- *\[7, 0, 0\]* - dim red light
|
||||
- *\[0, 0, 0\]* - no emission (default value)
|
||||
|
||||
### *light-passing*
|
||||
|
||||
Light ignores block if **true**
|
||||
|
||||
### *sky-light-passing*
|
||||
|
||||
Vertical sky light ray ignores block if **true**. (used for water)
|
||||
|
||||
## Physics
|
||||
|
||||
### *obstacle*
|
||||
|
||||
Block is not a physical obstacle if **false**
|
||||
|
||||
### *hitbox*
|
||||
|
||||
An array of 6 numbers describing an offset an size of a block hitbox.
|
||||
|
||||
Array *\[0.25, 0.0, 0.5, 0.75, 0.4, 0.3\]* describes hitbox width:
|
||||
- 0.75m width (from east to west)
|
||||
- 0.4m height
|
||||
- 0.3m length (from south to north)
|
||||
- offset 0.25m east
|
||||
- offset 0.0m up
|
||||
- offset 0.5m north
|
||||
|
||||
### *grounded*
|
||||
|
||||
Is block may only be set on a solid block and destructs on below block destruction.
|
||||
|
||||
### *selectable*
|
||||
|
||||
Cursor ray will ignore block if **false**.
|
||||
|
||||
### *replaceable*
|
||||
|
||||
Is block replaceable. Examples: air, water, grass, flower.
|
||||
|
||||
### *breakable*
|
||||
|
||||
Is block breakable by mouse click.
|
||||
|
||||
## Inventory
|
||||
|
||||
### *hidden*
|
||||
|
||||
If **true** an item will not be generated for block. **picking-item** must be specified
|
||||
|
||||
### *picking-item*
|
||||
|
||||
Item will be chosen on MMB click on the block.
|
||||
|
||||
Example: block `door:door_open` is hidden, so you need to specify `picking-item: "door:door.item"` to bind it to not hidden `door:door` block item.
|
||||
|
||||
### *script-name*
|
||||
|
||||
Used to specify block script name (to reuse one script to multiple blocks). Name must not contain `packid:scripts/` and extension. Just name.
|
||||
|
||||
### *ui-layout*
|
||||
|
||||
Block UI XML layout name. Default: string block id.
|
||||
|
||||
Examples for block `containermod:container`:
|
||||
- default: `containermod:container` (*containermod/layouts/container.xml*)
|
||||
- if `containermod:randombox` specified: (*containermod/layouts/randombox.xml*)
|
||||
|
||||
### *inventory-size*
|
||||
|
||||
Number of block inventory slots. Default - 0 (no inventory).
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# Visual
|
||||
|
||||
## *icon-type* and *icon* itself
|
||||
|
||||
Icon type defines a source of an item image displayed in inventory.
|
||||
- **none** - invisible type, used for *core:empty* only (empty item, like the air block). May be removed in future updates.
|
||||
- **sprite** - default type. 2D image. Requires *icon* set to *atlas_name:texture_name*. Example: *blocks:notfound*.
|
||||
There's two atlases available:
|
||||
- **blocks** (generated from *png* files in *res/textures/blocks/*)
|
||||
- **items** (generated from *png* files in *res/textures/items/*)
|
||||
- **block** - block preview. Block ID must be specified in **icon** property. Example: *base:wood*.
|
||||
|
||||
# Behaviour
|
||||
|
||||
## *placing-block*
|
||||
|
||||
Specifies what block will be placed on RMB click. Automatically specified in generated items.
|
||||
|
||||
Example: an items that places bazalt blocks:
|
||||
|
||||
```json
|
||||
"placing-block": "base:bazalt"
|
||||
```
|
||||
|
||||
## *emission*
|
||||
|
||||
Light emitted when player holds the item in hand.
|
||||
|
||||
An array of 3 integers - R, G, B of light in range \[0, 15\]
|
||||
|
||||
Examples:
|
||||
|
||||
- *\[15, 15, 15\]* - white with maximal intensity
|
||||
- *\[7, 0, 0\]* - dim red light
|
||||
- *\[0, 0, 0\]* - no emission (default value)
|
||||
|
||||
## *stack-size*
|
||||
|
||||
Maximal number of an item units in one slot. Default - 64.
|
||||
@@ -0,0 +1,102 @@
|
||||
# XML UI Building
|
||||
|
||||
# Specific types
|
||||
|
||||
**2D vector** - pair of numbers separated with comma.
|
||||
Examples:
|
||||
- "500,200"
|
||||
- "0.4,53.01"
|
||||
- "0,0"
|
||||
|
||||
**3D vector** - three numbers separated with comma.
|
||||
Examples:
|
||||
- "60,30,53"
|
||||
- "0.4,0.1,0.753"
|
||||
|
||||
**4D vector** - four numbers separated with comma.
|
||||
- "10,5,10,3"
|
||||
- "0.1,0.5,0.0,0.0"
|
||||
|
||||
**RGBA color** - only HEX notation available
|
||||
Examples:
|
||||
- "#FF8000" - opaque orange
|
||||
- "#FFFFFF80" - semi-transparent white
|
||||
- "#000000FF" - opaque black
|
||||
|
||||
# Common element attributes
|
||||
|
||||
- **id** - element identifier. Type: string.
|
||||
- **pos** - element position. Type: 2D vector.
|
||||
- **size** - element size. Type: 2D vector.
|
||||
- **color** - element color. Type: RGBA color.
|
||||
- **margin** - element margin. Type: 4D vector
|
||||
*left, top, right, bottom*
|
||||
- **visible** - element visibility. Type: boolean (true/false)
|
||||
- **position-func** - position supplier for an element (two numbers), called on every parent container size update or on element adding on a container. May be called before *on_hud_open*
|
||||
# Common *container* attributes
|
||||
|
||||
Buttons and panels are also containers.
|
||||
|
||||
- **padding** - element padding. Type: 4D vector.
|
||||
*left, top, right, bottom*
|
||||
**scrollable** - element scrollability. Works on panels only. Type: boolean
|
||||
|
||||
# Common *panel* attributes
|
||||
|
||||
Buttons are also panels.
|
||||
|
||||
- **max-length** - maximal length of panel stretching before scrolling (if scrollable = true). Type: number
|
||||
# Common elements
|
||||
|
||||
## *button*
|
||||
|
||||
Inner text is a button text.
|
||||
|
||||
- **text-align** - inner text alignment (*left/center/right*). Type: string.
|
||||
- **onclick** - Lua function called on button press.
|
||||
|
||||
## *image*
|
||||
|
||||
- **src** - name of an image stored in textures folder. Extension is not specified. Type: string.
|
||||
Example: *gui/error*
|
||||
|
||||
## *trackbar*
|
||||
|
||||
- **min** - minimal value. Type: number. Default: 0
|
||||
- **max** - maximal value. Type: number. Default: 1
|
||||
- **value** - initial value. Type: number. Default: 0
|
||||
- **step** - track step size. Type: number: Default: 1
|
||||
- **track-width** track pointer width (in steps). Type: number. Default: 1
|
||||
- **consumer** - Lua function - new value consumer
|
||||
- **supplier** - Lua function - value supplier
|
||||
|
||||
# Inventory elements
|
||||
|
||||
## *inventory*
|
||||
|
||||
Element is a container. Does not have specific attributes.
|
||||
|
||||
> [!WARNING]
|
||||
> Inventories position is controlled by the engine and can not be changed by attributes *pos* and *margin*
|
||||
|
||||
## *slot*
|
||||
|
||||
Element must be in direct sub-element of *inventory*.
|
||||
- **index** - inventory slot index (starting from 0). Type: integer
|
||||
- **item-source** - content access panel behaviour (infinite source of an item). Type: boolean
|
||||
- **sharefunc** - Lua event called on <btn>LMB</btn> + <btn>Shift</btn>. Inventory id and slot index passed as arguments.
|
||||
- **updatefunc** - Lua event called on slot content update.Inventory id and slot index passed as arguments.
|
||||
- **onrightclick** - Lua event called on <btn>RMB</btn> click. Inventory id and slot index passed as arguments.
|
||||
|
||||
## *slots-grid*
|
||||
|
||||
- **start-index** - inventory slot index of the first slot. Type: integer
|
||||
- **rows** - number of grid rows (unnecessary if *cols* and *count* specified). Type: integer
|
||||
- **cols** - number of grid columns (unnecessary if *rows* and *count* specified). Type: integer
|
||||
- **count** - total number of slots in grid (unnecessary if *rows* and *cols* specified). Type: integer
|
||||
- **interval** - visual slots interval. Type: number
|
||||
- **padding** - grid padding (not slots interval). Type: number. (*deprecated*)
|
||||
- **sharefunc** - Lua event called on <btn>LMB</btn> + <btn>Shift</btn>. Inventory id and slot index passed as arguments.
|
||||
- **updatefunc** - Lua event called on slot content update.Inventory id and slot index passed as arguments.
|
||||
- **onrightclick** - Lua event called on <btn>RMB</btn> click. Inventory id and slot index passed as arguments.
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Assets preloading (*preload.json* file)
|
||||
|
||||
`preload.json` in content-pack folder is used for specifying additional assets should be loaded, like sounds.
|
||||
|
||||
The file contains following categories available:
|
||||
- fonts
|
||||
- shaders
|
||||
- textures
|
||||
- sounds
|
||||
|
||||
> [!NOTE]
|
||||
> Sound loading with all variations following template:
|
||||
> (sound: *sound_name*) -> *sound_name.ogg, sound_name_1.ogg, sound_name_2.ogg, ...*
|
||||
> or *sound_name_0.ogg, sound_name_1.ogg, sound_name_2.ogg, ...*
|
||||
|
||||
Adding sound `packid:sounds/events/explosion.ogg` with all variants example:
|
||||
```json
|
||||
{
|
||||
"sounds": [
|
||||
"events/explosion"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Sound will be available as "events/explosion"
|
||||
|
||||
Additional load settings example:
|
||||
```json
|
||||
{
|
||||
"sounds": [
|
||||
{
|
||||
"name": "events/explosion",
|
||||
"keep-pcm": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
*preload.json* example from `core:` package (`res/preload.json`):
|
||||
```json
|
||||
{
|
||||
"shaders": [
|
||||
"ui3d",
|
||||
"screen",
|
||||
"background",
|
||||
"skybox_gen"
|
||||
],
|
||||
"textures": [
|
||||
"misc/moon",
|
||||
"misc/sun",
|
||||
"gui/crosshair"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
@@ -0,0 +1,195 @@
|
||||
# Audio
|
||||
|
||||
## Definitions
|
||||
|
||||
### Backend
|
||||
|
||||
Internal audio system implementation controlling audio output.
|
||||
- NoAudio - dummy audio used on OpenAL initialize fail or if audio is disabled by the *settings.toml*: *\[audio\] enabled=false*
|
||||
- ALAudio - OpenAL audio used
|
||||
|
||||
### Channel
|
||||
|
||||
Defines a sound sources category for group volume control, effects and pause.
|
||||
|
||||
Now the engine has following channels:
|
||||
- *master* - controls other channels volume. Should not be used as a target channel when playing an audio.
|
||||
- *ui* - ui elements sounds (button clicks and other)
|
||||
- *regular* - world sounds, that will be paused with the game.
|
||||
- *ambient* - same as *regular* but added for background and ambient sounds/streams like weather.
|
||||
- *music* - music channel.
|
||||
|
||||
Channels are controlled by the engine and currently are not available in scripts.
|
||||
|
||||
### Speaker
|
||||
|
||||
One-time use playing audio controller for sound or stream. Speaker is destroying after stop (**stop** method call or audio track end if not looped)
|
||||
|
||||
> [!NOTE]
|
||||
> Speaker access is performed using 64 bit integer identifiers that **will not be reused** after speaker destruction. You should avoid storing direct references and pointers instead of ID.
|
||||
|
||||
Speaker ID starts with 1, so 0 means audio play failure.
|
||||
|
||||
### Sound
|
||||
|
||||
Audio data loaded in memory to play multiple simultaneous instances from multiple sources. Can give access to loaded PCM data.
|
||||
|
||||
### PCMStream (PCM data source)
|
||||
|
||||
Stream used by an audio stream as an audio data source. Implementation depends on audio file format, not a backend. This interface may be used to implement network audio stream.
|
||||
|
||||
### Stream
|
||||
|
||||
Streaming audio. Not fully loading to the memory. Cannot be played via multiple speakers simultaneously.
|
||||
|
||||
## Formats support
|
||||
|
||||
- WAV: 8 and 16 bit supported (24 bit is not supported by OpenAL)
|
||||
- OGG: implemented with libvorbis
|
||||
|
||||
## Additional information
|
||||
|
||||
> [!WARNING]
|
||||
> **Stereo** audio played with OpenAL will ignore 3D position relative to the listener. Sounds that supposed to be played at specific world position must be **mono**
|
||||
|
||||
## Scripting Audio API
|
||||
|
||||
### Playing audio
|
||||
|
||||
Library **audio** contains available Audio API in Lua scripts.
|
||||
|
||||
```lua
|
||||
audio.play_stream(
|
||||
-- audio file location
|
||||
name: string,
|
||||
-- audio source world position
|
||||
x: number, y: number, z: number,
|
||||
-- audio gain (0.0 - 1.0)
|
||||
volume: number
|
||||
-- audio playback speed (positive number)
|
||||
pitch: number,
|
||||
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
||||
channel: string,
|
||||
-- [optional] loop stream (default - false)
|
||||
loop: bool
|
||||
) -> int
|
||||
```
|
||||
|
||||
Plays streaming audio from the specified file at the specified world position. Returns speaker ID.
|
||||
|
||||
```lua
|
||||
audio.play_stream_2d(
|
||||
-- audio file location
|
||||
name: string,
|
||||
-- audio gain (0.0 - 1.0)
|
||||
volume: number
|
||||
-- audio playback speed (positive number)
|
||||
pitch: number,
|
||||
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
||||
channel: string,
|
||||
-- [optional] loop stream (default - false)
|
||||
loop: bool
|
||||
) -> int
|
||||
|
||||
```
|
||||
|
||||
Plays streaming audio from the specified file. Returns speaker ID.
|
||||
|
||||
```lua
|
||||
audio.play_sound(
|
||||
-- name of a loaded sound without pack prefix, "sounds/", variant number and extension
|
||||
-- example: "steps/stone" to play sound loaded from "sounds/steps/stone.ogg" or any of its variant
|
||||
-- variant will be randomly chosen
|
||||
name: string,
|
||||
-- audio source world position
|
||||
x: number, y: number, z: number,
|
||||
-- audio gain (0.0 - 1.0)
|
||||
volume: number
|
||||
-- audio playback speed (positive number)
|
||||
pitch: number,
|
||||
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
||||
channel: string,
|
||||
-- [optional] loop sound (default - false)
|
||||
loop: bool
|
||||
) -> int
|
||||
```
|
||||
|
||||
Plays the specified sound on the specified position in world. Returns speaker ID.
|
||||
|
||||
```lua
|
||||
audio.play_sound_2d(
|
||||
-- name of a loaded sound without pack prefix, "sounds/", variant number and extension
|
||||
-- example: "steps/stone" to play sound loaded from "sounds/steps/stone.ogg" or any of its variant
|
||||
-- variant will be randomly chosen
|
||||
name: string,
|
||||
-- audio gain (0.0 - 1.0)
|
||||
volume: number
|
||||
-- audio playback speed (positive number)
|
||||
pitch: number,
|
||||
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
||||
channel: string,
|
||||
-- [optional] loop sound (default - false)
|
||||
loop: bool
|
||||
) -> int
|
||||
```
|
||||
|
||||
Plays the specified sound. Returns speaker ID.
|
||||
|
||||
### Speaker interaction
|
||||
|
||||
Interaction with a non-existing or destroyed speaker will be ignored.
|
||||
|
||||
|
||||
```lua
|
||||
-- stop audio playback and destroy the speaker
|
||||
audio.stop(speakerid: integer)
|
||||
|
||||
-- pause speaker
|
||||
audio.pause(speakerid: integer)
|
||||
|
||||
-- unpause speaker
|
||||
audio.resume(speakerid: integer)
|
||||
|
||||
-- set audio loop
|
||||
audio.set_loop(speakerid: integer, state: bool)
|
||||
|
||||
-- check if audio is in loop (false if does not exists)
|
||||
audio.is_loop(speakerid: integer) -> bool
|
||||
|
||||
-- get audio gain value (0.0 if does not exists)
|
||||
audio.get_volume(speakerid: integer) -> number
|
||||
|
||||
-- set audio gain value
|
||||
audio.set_volume(speakerid: integer, volume: number)
|
||||
|
||||
-- get audio playback speed (1.0 if does not exists)
|
||||
audio.get_pitch(speakerid: integer) -> number
|
||||
|
||||
-- set audio playback speed
|
||||
audio.set_pitch(speakerid: integer, pitch: number)
|
||||
|
||||
-- get current audio playback time in seconds (0.0 if does not exists)
|
||||
audio.get_time(speakerid: integer) -> number
|
||||
|
||||
-- set audio playback time position in seconds
|
||||
audio.set_time(speakerid: integer, time: number)
|
||||
|
||||
-- get audio source world position (nil if does not exists)
|
||||
audio.get_position(speakerid: integer) -> number, number, number
|
||||
|
||||
-- set audio source world position
|
||||
audio.set_position(speakerid: integer, x: number, y: number, z: number)
|
||||
|
||||
-- get audio source movement speed in world (nil if does not exists)
|
||||
-- (OpenAL uses it for Doppler effect simulation)
|
||||
audio.get_velocity(speakerid: integer) -> number, number, number
|
||||
|
||||
-- set audio source movement speed in world
|
||||
-- (OpenAL uses it for Doppler effect simulation)
|
||||
audio.set_velocity(speakerid: integer, x: number, y: number, z: number)
|
||||
|
||||
-- get audio duration
|
||||
-- returns 0, if does not exists
|
||||
-- also returns 0, if duration is unknown (example: radio)
|
||||
audio.get_duration(speakerid: integer) -> number
|
||||
```
|
||||
@@ -0,0 +1,523 @@
|
||||
# Scripting
|
||||
|
||||
Project uses LuaJIT as a scripting language.
|
||||
|
||||
## Core functions
|
||||
|
||||
```lua
|
||||
require "packid:module_name" -- load Lua module from pack-folder/modules/
|
||||
-- no extension included, just name
|
||||
|
||||
-- deprecated functions
|
||||
load_script("packid:scripts/script_name.lua") -- load Lua script if not loaded yet
|
||||
load_script("packid:scripts/script_name.lua", true) -- load Lua script anyway
|
||||
```
|
||||
|
||||
## *player* library
|
||||
|
||||
|
||||
```python
|
||||
player.get_pos(playerid: int) -> number, number, number
|
||||
```
|
||||
Returns x, y, z coordinates of the player
|
||||
|
||||
```python
|
||||
player.set_pos(playerid: int, x: number, y: number, z: number)
|
||||
```
|
||||
|
||||
Set player position
|
||||
|
||||
```python
|
||||
player.get_rot(playerid: int) -> number, number
|
||||
```
|
||||
|
||||
Returns x, y of camera rotation (radians)
|
||||
|
||||
```python
|
||||
player.set_rot(playerid: int, x: number, y: number, z: number)
|
||||
```
|
||||
|
||||
Set camera rotation (radians)
|
||||
|
||||
```python
|
||||
player.get_inventory(playerid: int) -> int, int
|
||||
```
|
||||
|
||||
Returns player inventory ID and selected slot index (0-9)
|
||||
|
||||
## *world* library
|
||||
|
||||
```python
|
||||
world.get_day_time() -> number
|
||||
```
|
||||
|
||||
Returns current day time in range \[0.0-1.0\] where 0.0 and 1.0 - midnight, 0.5 - noon.
|
||||
|
||||
```python
|
||||
world.set_day_time(time: number)
|
||||
```
|
||||
|
||||
Set day time value.
|
||||
|
||||
```python
|
||||
world.get_total_time() -> number
|
||||
```
|
||||
|
||||
Returns total time passed in the world
|
||||
|
||||
```python
|
||||
world.get_seed() -> int
|
||||
```
|
||||
|
||||
Returns world seed.
|
||||
|
||||
## *gui* library
|
||||
|
||||
Library contains ui elements access functions. Library should not be directly used, because script *layouts/layout_name.xml.lua* already has a generated variable **document** (instance of **Document**)
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
print(document.some_button.text) -- where 'some_button' is an element id
|
||||
document.some_button.text = "new text"
|
||||
```
|
||||
|
||||
## **inventory** library
|
||||
|
||||
Library for inventories interaction.
|
||||
|
||||
```python
|
||||
inventory.get(invid: int, slot: int) -> int, int
|
||||
```
|
||||
|
||||
Requires an inventory ID and slot index. Returns item ID and count. ID = 0 (core:empty) means that slot is empty.
|
||||
|
||||
```python
|
||||
inventory.set(invid: int, slot: int, itemid: int, count: int)
|
||||
```
|
||||
|
||||
Set slot content.
|
||||
|
||||
```python
|
||||
inventory.size(invid: int) -> int
|
||||
```
|
||||
|
||||
Returns inventory size (slots number). Throws an exception if there's no inventory having specified ID.
|
||||
|
||||
```python
|
||||
inventory.add(invid: int, itemid: int, count: int) -> int
|
||||
```
|
||||
|
||||
Add an item to the specified inventory. Returns remaining count if could not to add fully.
|
||||
|
||||
```python
|
||||
inventory.get_block(x: int, y: int, z: int) -> int
|
||||
```
|
||||
|
||||
Returns block inventory ID or 0.
|
||||
|
||||
```python
|
||||
inventory.bind_block(invid: int, x: int, y: int, z: int)
|
||||
```
|
||||
|
||||
Bind inventory to the specified block.
|
||||
|
||||
```python
|
||||
inventory.unbind_block(x: int, y: int, z: int)
|
||||
```
|
||||
|
||||
Unbind inventory from the specified block.
|
||||
|
||||
> [!WARNING]
|
||||
> Unbound inventories will be deleted on world close.
|
||||
|
||||
```python
|
||||
inventory.clone(invid: int) -> int
|
||||
```
|
||||
|
||||
Create inventory copy. Returns the created copy ID.
|
||||
|
||||
## *block* library
|
||||
|
||||
```python
|
||||
block.name(blockid: int) -> str
|
||||
```
|
||||
|
||||
Returns block string ID (name) by index
|
||||
|
||||
```python
|
||||
block.index(name: str) -> int
|
||||
```
|
||||
|
||||
Returns block integer ID (index) by name
|
||||
|
||||
```python
|
||||
block.get(x: int, y: int, z: int) -> int
|
||||
```
|
||||
|
||||
Returns integer ID by block position
|
||||
|
||||
```python
|
||||
block.get_states(x: int, y: int, z: int) -> int
|
||||
```
|
||||
|
||||
Returns block state (rotation + additional information) as an integer.
|
||||
|
||||
```python
|
||||
block.set(x: int, y: int, z: int, id: int, states: int)
|
||||
```
|
||||
|
||||
Set block with specified integer ID and state (default - 0) at specified position.
|
||||
|
||||
> [!WARNING]
|
||||
> `block.set` does not trigger on_placed.
|
||||
|
||||
```python
|
||||
block.is_solid_at(x: int, y: int, z: int) -> bool
|
||||
```
|
||||
|
||||
Check if block at the specified position is solid.
|
||||
|
||||
```python
|
||||
block.is_replaceable_at(x: int, y: int, z: int) -> bool
|
||||
```
|
||||
Check if block may be placed at specified position. (Examples: air, water, grass, flower)
|
||||
|
||||
```python
|
||||
block.defs_count() -> int
|
||||
```
|
||||
|
||||
Returns count of available block IDs.
|
||||
|
||||
Following three functions return direction vectors based on block rotation.
|
||||
|
||||
|
||||
```python
|
||||
block.get_X(x: int, y: int, z: int) -> int, int, int
|
||||
```
|
||||
|
||||
Returns X: integer direction vector of the block at specified coordinates.
|
||||
Example: no rotation: 1, 0, 0
|
||||
|
||||
```python
|
||||
block.get_Y(x: int, y: int, z: int) -> int, int, int
|
||||
```
|
||||
|
||||
Returns Y: integer direction vector of the block at specified coordinates.
|
||||
Example: no rotation: 0, 1, 0
|
||||
|
||||
```python
|
||||
block.get_Z(x: int, y: int, z: int) -> int, int, int
|
||||
```
|
||||
|
||||
Returns Z: integer direction vector of the block at specified coordinates.
|
||||
Example: no rotation: 0, 0, 1
|
||||
|
||||
### User bits
|
||||
|
||||
Part of a voxel data used for scripting. Size: 8 bit.
|
||||
|
||||
```python
|
||||
block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
|
||||
```
|
||||
|
||||
Get specified bits as an unsigned integer.
|
||||
|
||||
```python
|
||||
block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
|
||||
```
|
||||
Set specified bits.
|
||||
|
||||
## *item* library
|
||||
|
||||
|
||||
```python
|
||||
item.name(itemid: int) -> str
|
||||
```
|
||||
|
||||
Returns item string ID (name) by index
|
||||
|
||||
```python
|
||||
item.index(name: str) -> int
|
||||
```
|
||||
|
||||
Returns item integer ID (index) by name
|
||||
|
||||
```python
|
||||
item.stack_size(itemid: int) -> int
|
||||
```
|
||||
|
||||
Returns max stack size for the item
|
||||
|
||||
```python
|
||||
item.defs_count() -> int
|
||||
```
|
||||
|
||||
Returns count of available item IDs.
|
||||
|
||||
## *hud* library
|
||||
|
||||
|
||||
```python
|
||||
hud.open_inventory()
|
||||
```
|
||||
|
||||
Open player inventory
|
||||
|
||||
```python
|
||||
hud.close_inventory()
|
||||
```
|
||||
|
||||
Close inventory
|
||||
|
||||
```python
|
||||
hud.open_block(x: int, y: int, z: int) -> int, str
|
||||
```
|
||||
|
||||
Open block UI and inventory. Throws an exception if block has no UI layout.
|
||||
|
||||
Returns block inventory ID (if *"inventory-size"=0* a virtual inventory will be created), and UI layout ID.
|
||||
|
||||
> [!NOTE]
|
||||
> Only one block may be open at same time
|
||||
|
||||
```python
|
||||
hud.open_permanent(layoutid: str)
|
||||
```
|
||||
|
||||
Add element to the screen. The element will be removed on world close only.
|
||||
**inventory** element will be bound to the player inventory.
|
||||
|
||||
```python
|
||||
hud.close(layoutid: str)
|
||||
```
|
||||
|
||||
Remove an element from the screen
|
||||
|
||||
## Block events
|
||||
|
||||
```lua
|
||||
function on_placed(x, y, z, playerid)
|
||||
```
|
||||
|
||||
Called on block placed by player
|
||||
|
||||
```lua
|
||||
function on_broken(x, y, z, playerid)
|
||||
```
|
||||
|
||||
Called on block broken by player
|
||||
|
||||
```lua
|
||||
function on_interact(x, y, z, playerid) -> bool
|
||||
```
|
||||
|
||||
Called on block RMB click interaction. Prevents block placing if **true** returned.
|
||||
|
||||
```lua
|
||||
function on_update(x, y, z)
|
||||
```
|
||||
|
||||
Called on block update (near block changed)
|
||||
|
||||
```lua
|
||||
function on_random_update(x, y, z)
|
||||
```
|
||||
|
||||
Called on random block update (grass growth)
|
||||
|
||||
```lua
|
||||
function on_blocks_tick(tps: int)
|
||||
```
|
||||
|
||||
Called tps (20) times per second.
|
||||
|
||||
## Item events
|
||||
|
||||
```lua
|
||||
function on_use(playerid: int)
|
||||
```
|
||||
|
||||
Called on RMB click out of a block.
|
||||
|
||||
```lua
|
||||
function on_use_on_block(x: int, y: int, z: int, playerid: int)
|
||||
```
|
||||
|
||||
Called on block RMB click. Prevents block **placing-block** placing if returns **true**
|
||||
|
||||
```lua
|
||||
function on_block_break_by(x: int, y: int, z: int, playerid: int)
|
||||
```
|
||||
|
||||
Called on block LMB click (unbreakable blocks included). Prevents block destruction if returns **true**.
|
||||
|
||||
## World events
|
||||
|
||||
Script *scripts/world.lua* events.
|
||||
|
||||
```lua
|
||||
function on_world_open()
|
||||
```
|
||||
|
||||
Called on world open.
|
||||
|
||||
```lua
|
||||
function on_world_save()
|
||||
```
|
||||
|
||||
Called before world save.
|
||||
|
||||
```lua
|
||||
function on_world_tick()
|
||||
```
|
||||
|
||||
Called 20 times per second
|
||||
|
||||
```lua
|
||||
function on_world_quit()
|
||||
```
|
||||
|
||||
Called on world close (after saving)
|
||||
|
||||
## Layout events
|
||||
|
||||
Script *layouts/layout_name.xml.lua* events.
|
||||
|
||||
```lua
|
||||
function on_open(invid: int, x: int, y: int, z: int)
|
||||
```
|
||||
|
||||
Called on element added to the screen.
|
||||
invid=0 if no inventory bound
|
||||
x,y,z=0 if no block bound
|
||||
|
||||
```lua
|
||||
function on_close(invid: int)
|
||||
```
|
||||
|
||||
Called on element removed from the screen.
|
||||
|
||||
## HUD events
|
||||
|
||||
Script *scripts/hud.lua* events.
|
||||
|
||||
|
||||
```lua
|
||||
function on_hud_open(playerid: int)
|
||||
```
|
||||
|
||||
Called after world open.
|
||||
|
||||
```lua
|
||||
function on_hud_close(playerid: int)
|
||||
```
|
||||
|
||||
Called on world close (before saving)
|
||||
|
||||
## Engine libraries
|
||||
|
||||
### file
|
||||
|
||||
Filesystem interaction library.
|
||||
|
||||
```python
|
||||
file.resolve(path: str) -> str
|
||||
```
|
||||
|
||||
Function turns *entry_point:path* (example *user:worlds/house1*) to a regular path. (example *C://Users/user/.voxeng/worlds/house1*)
|
||||
|
||||
> [!NOTE]
|
||||
> The function should be used for debug only. *entry_point:path* notation is required in all **file** functions.
|
||||
|
||||
Resulting path is not canonical and may be relative.
|
||||
|
||||
```python
|
||||
file.read(path: str) -> str
|
||||
```
|
||||
|
||||
Read whole text file.
|
||||
|
||||
```python
|
||||
file.read_bytes(path: str) -> array of integers
|
||||
```
|
||||
|
||||
Read file into bytes array.
|
||||
|
||||
```python
|
||||
file.write(path: str, text: str) -> nil
|
||||
```
|
||||
|
||||
Overwrite text file.
|
||||
|
||||
```python
|
||||
file.write_bytes(path: str, data: array of integers)
|
||||
```
|
||||
|
||||
Overwrite binary file with bytes array.
|
||||
|
||||
```python
|
||||
file.length(path: str) -> int
|
||||
```
|
||||
|
||||
Get file length (bytes) or 0.
|
||||
|
||||
```python
|
||||
file.exists(path: str) -> bool
|
||||
```
|
||||
|
||||
Check if file or directory exist.
|
||||
|
||||
```python
|
||||
file.isfile(path: str) -> bool
|
||||
```
|
||||
|
||||
Check if the path points to a file.
|
||||
|
||||
```python
|
||||
file.isdir(path: str) -> bool
|
||||
```
|
||||
|
||||
Check if the path points to a directory.
|
||||
|
||||
```python
|
||||
file.mkdir(path: str) -> bool
|
||||
```
|
||||
|
||||
Create directory. Returns true if new directory created
|
||||
|
||||
```python
|
||||
file.mkdirs(path: str) -> bool
|
||||
```
|
||||
|
||||
Create directories chain. Returns true if new directory created
|
||||
|
||||
### time
|
||||
|
||||
```python
|
||||
time.uptime() -> float
|
||||
```
|
||||
|
||||
Returns time elapsed since the engine started.
|
||||
|
||||
## Available modules
|
||||
|
||||
### TOML serialization/deserialization
|
||||
|
||||
```lua
|
||||
local toml = require "core:toml"
|
||||
|
||||
local t = {a=53, b=42, s="test", sub={x=1, y=6}}
|
||||
local s = toml.serialize(t)
|
||||
print(s)
|
||||
local t2 = toml.deserialize(s)
|
||||
```
|
||||
output:
|
||||
```toml
|
||||
b = 42
|
||||
s = "test"
|
||||
a = 53
|
||||
[sub]
|
||||
y = 6
|
||||
x = 1
|
||||
```
|
||||
@@ -0,0 +1,20 @@
|
||||
# Block Models
|
||||
|
||||
Block model may be created with following properties:
|
||||
|
||||
```js
|
||||
"model": "custom",
|
||||
"model-primitives": {
|
||||
"aabbs": [
|
||||
// list of AABB primitives
|
||||
],
|
||||
// ... other primitives
|
||||
}
|
||||
```
|
||||
|
||||
**AABB** primitive is an array of values:
|
||||
```
|
||||
[x, y, z, width, height, depth, texture names for all 6 sides]
|
||||
```
|
||||
|
||||
**tetragon** primitive (more like parallelogram) an array of three vectors, describing primitive position, X vector \* width, Y vector \* height.
|
||||
Reference in New Issue
Block a user