109 lines
4.5 KiB
Plaintext
109 lines
4.5 KiB
Plaintext
# simple_protection API
|
|
|
|
This file provides information about the API of simple_protection for the use in
|
|
custom mods. The API might change slightly when the development goes on, so avoid
|
|
using internal tables or functions which are not documented here.
|
|
|
|
### Table of contents
|
|
|
|
* Types: Custom tables or values
|
|
* Helper functions: General purpose functions
|
|
* Protection management: Claim-specific API functions
|
|
* Callbacks: Registrable callbacks
|
|
|
|
### Notation
|
|
|
|
* `function_name(arg1, arg2, ...)` -> `returned data type`
|
|
* Function description
|
|
|
|
|
|
## Types
|
|
|
|
* `ClaimData` -> `table`
|
|
```
|
|
{
|
|
owner = "foobar", -- string, owner of the area
|
|
shared = { "covfefe", "leprechaun" },
|
|
-- ^ table, list of players who explicitly have access to this area
|
|
}
|
|
```
|
|
* `ClaimIndex` -> `?`
|
|
* This might be any value, depending on the database backend.
|
|
* Can be obtained with `get_claim` and is used for `set_claim`
|
|
|
|
|
|
## Helper functions
|
|
|
|
These functions are grouped so that they make sense and then sorted alphabetically.
|
|
|
|
* `s_protect.can_access(pos, player_name)` -> `boolean`
|
|
* Returns whether the player may modify the given position
|
|
* `pos`: Position as a `vector`
|
|
* `player_name`: Is a `string` for the player to check
|
|
* `nil`: Always returns `false`
|
|
* `""`: Returns `true`. Warning: `get_player_name()` returns this value on
|
|
objects which are not players, such as Lua entities.
|
|
* `s_protect.get_area_bounds(pos)` -> `vector, vector`
|
|
* Returns the minimal node position (1st value) and maximal node position
|
|
(2nd value) of the current claim. The coordinate values are inside the claim.
|
|
* `pos`: Position as a `vector`
|
|
* `s_protect.get_center(pos)` -> `vector`
|
|
* Returns the center node position of the current claim near to `pos.y`.
|
|
* `pos`: Position as a `vector`
|
|
* `s_protect.get_location(pos)` -> `vector`
|
|
* Returns the location of the given claim (whole numbers) in claim-coordinates
|
|
* `pos`: Position as a `vector`
|
|
* This function is only helpful to iterate through multiple claims.
|
|
* `s_protect.load_config()`
|
|
* Causes simple_protection to (initialize and) reload the configuration.
|
|
|
|
|
|
## Protection management
|
|
|
|
* `s_protect.get_claim(pos)` -> `ClaimData, ClaimIndex`
|
|
* Returns the area information or `nil` when no area was found at the given
|
|
position.
|
|
* `pos`: Position as a `vector`
|
|
* `s_protect.get_player_claims(owner)` -> `table, count`
|
|
* Returns a table of claims which the player owns, whereas `ClaimIndex` is the
|
|
key and `ClaimData` the value of the resulting table. The second argument
|
|
describes how many entries the table has (i.e. how many claims).
|
|
* `owner`: Player name as `string`
|
|
* `s_protect.set_claim(data, index)`
|
|
* Updates the area data for the given index. It will be saved automatically.
|
|
* `data`: Area information as `ClaimData`
|
|
* `index`: `ClaimIndex` provided by `get_claim`
|
|
* `s_protect.update_claims(update_table)`
|
|
* Updates multiple areas according to the supplied table
|
|
* `update_table`: `table` of areas to update, whereas the key is `ClaimIndex`
|
|
and the value `ClaimData`. Set the value to `nil` to remove the claim.
|
|
* `s_protect.is_shared(id, player_name)` -> `boolean`
|
|
* Returns whether the owner shared an area (or multiple) with `player_name`
|
|
* `id`: Can be either `ClaimData` or the owner name as `string`:
|
|
* Type `ClaimData`: Checks whether `player_name` is contained in
|
|
the given area's share list.
|
|
* Type `string`: Checks whether all areas of the given owner are
|
|
shared with `player_name`
|
|
* `player_name`: `string`, the player to check
|
|
|
|
|
|
## Callbacks
|
|
|
|
* `s_protect.registered_on_access(func)`
|
|
* Override or extend access to a certain claim. Depending on the returned
|
|
value of the registered function.
|
|
* `func`: `function(pos, player_name, owner_name)` called in `s_protect.can_access`.
|
|
* Is only called on protected areas. Use settings to control unclaimed areas.
|
|
* Must return a boolean or `nil`
|
|
* `pos`: `vector` position of the interaction
|
|
* `player_name`: `string` name of the interacting player
|
|
* `owner_name`: `string` name of the claim owner (player)
|
|
* If `func() -> false`: Access is denied instantly regardless of shared areas.
|
|
* If `func() -> true`: Access is granted if no other callback returns `false`.
|
|
* If `func() -> nil`: Normal protection handling
|
|
* `s_protect.register_subcommand(name, func)`
|
|
* Registers a new subcommand for `/area`; throws errors on failure
|
|
* `name`: `string` name of the new command
|
|
* `func`: `function` to call when the command is executed
|
|
* See "Chat command definition" in the Minetest core Lua API.
|