From 03b97bc5464fb116755aecf04b50545242c8fcb1 Mon Sep 17 00:00:00 2001 From: varttist Date: Sat, 7 Nov 2026 19:01:51 +0300 Subject: [PATCH] `core_namespace`: 5.18 update --- core_namespace.lua | 51 -- core_namespace/registration/translations.lua | 59 ++ core_namespace/utilities.lua | 558 ++++++++----------- specs/Color.lua | 47 +- 4 files changed, 326 insertions(+), 389 deletions(-) create mode 100644 core_namespace/registration/translations.lua diff --git a/core_namespace.lua b/core_namespace.lua index de57147..bd58b8b 100644 --- a/core_namespace.lua +++ b/core_namespace.lua @@ -239,57 +239,6 @@ function core.get_hit_params(groups, tool_capabilities , time_from_last_punch) e --- Translations - ---- is a simple wrapper around ---- `core.translate`, and `core.get_translator(textdomain)(str, ...)` is ---- equivalent to `core.translate(textdomain, str, ...)`. ---- It is intended to be used in the following way, so that it avoids verbose ---- repetitions of `core.translate`: ---- ---- local S = core.get_translator(textdomain) ---- S(str, ...) ---- ---- As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead. ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L3329-L3338) ---- ---- @param text_domain string ---- @return fun(str: string, ...):string -function core.get_translator(text_domain) end ---- translates the string `str` with ---- the given `textdomain` for disambiguation. The textdomain must match the ---- textdomain specified in the translation file in order to get the string ---- translated. This can be used so that a string is translated differently in ---- different contexts. ---- It is advised to use the name of the mod as textdomain whenever possible, to ---- avoid clashes with other mods. ---- This function must be given a number of arguments equal to the number of ---- arguments the translated string expects. ---- Arguments are literal strings -- they will not be translated, so if you want ---- them to be, they need to come as outputs of `core.translate` as well. ---- ---- For instance, suppose we want to translate "@1 Wool" with "@1" being replaced ---- by the translation of "Red". We can do the following: ---- ---- local S = core.get_translator() ---- S("@1 Wool", S("Red")) ---- ---- This will be displayed as "Red Wool" on old clients and on clients that do ---- not have localization enabled. However, if we have for instance a translation ---- file named `wool.fr.tr` containing the following: ---- ---- \@1 Wool=Laine @1 ---- Red=Rouge ---- ---- this will be displayed as "Laine Rouge" on clients with a French locale. ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L3340-L3365) ---- ---- @param textdomain string ---- @param str string ---- @return string -function core.translate(textdomain, str, ...) end diff --git a/core_namespace/registration/translations.lua b/core_namespace/registration/translations.lua new file mode 100644 index 0000000..53a5fe7 --- /dev/null +++ b/core_namespace/registration/translations.lua @@ -0,0 +1,59 @@ +---Version: 5.18 +---@meta + +--- Translations --- + +---Is a simple wrapper around `core.translate` and `core.translate_n`. +--- +---After `local S, PS = core.get_translator(textdomain)`, +---we have `S(str, ...)` equivalent to `core.translate(textdomain, str, ...)`, and +---`PS(str, str_plural, n, ...)` to `core.translate_n(textdomain, str, str_plural, n, ...)`. +---It is intended to be used in the following way, +---so that it avoids verbose repetitions of `core.translate`: +---```lua +--- local S, PS = core.get_translator(textdomain) +--- S(str, ...) +---``` +--- +---As an extra commodity, if `textdomain` is nil, it is assumed to be `""` instead. +---@param textdomain string? +---@return fun(str:string, ...):string, fun(str:string, ...):string +function core.get_translator(textdomain) end + +---Translates the string `str` with the given `textdomain` for disambiguation. +--- +---The textdomain must match the textdomain specified in the translation file +---in order to get the string translated. This can be used so that a string +---is translated differently in different contexts. It is advised to use +---the name of the mod as textdomain whenever possible, to avoid clashes with other mods. +--- +---This function must be given an amount of arguments equal to the amount of arguments +---the translated string expects. Arguments are literal strings -- they will not be translated. +---@param textdomain string +---@param str string +---@param ... string +---@return string +function core.translate(textdomain, str, ...) end + +---Translates the string `str` with the given `textdomain` for disambiguation. +--- +---The value of `n`, which must be a nonnegative integer, +---is used to decide whether to use the singular or the plural version of the string. +--- +---Depending on the locale of the client, the choice between singular and plural +---might be more complicated, but the choice will be done automatically using the value of `n`. +---@param textdomain string +---@param str string +---@param str_plural string +---@param n string +---@param ... string +---@return string +function core.translate_n(textdomain, str, str_plural, n, ...) end + +---Resolves translations in the given string just like the client would, +---using the translation files for `lang_code`. For this to have any effect, +---the string needs to contain translation markup, +---e.g. `core.get_translated_string("fr", S("Hello"))`. +---@param lang_code string +---@param str string +function core.get_translated_string(lang_code, str) end diff --git a/core_namespace/utilities.lua b/core_namespace/utilities.lua index 55887c2..8e448e6 100644 --- a/core_namespace/utilities.lua +++ b/core_namespace/utilities.lua @@ -1,370 +1,288 @@ ---- @meta +---Version: 5.18 +---@meta +--- Utilities --- ---- Returns the currently loading mod's name, when loading a mod. ---- - Returns nil if not loading a mod. ---- - Only works during mod loading (i.e. when a mod calls this function from ---- its top-level scope, or from a function called during mod loading). ---- - Useful for libraries to determine which mod is loading them, for ---- example to access that mod's mod storage. ---- @see core.get_modpath ---- @see core.get_modnames ---- @see core.get_worldpath ---- @return string returns the currently loading mod's name, when loading a mod. +---Returns the currently loading mod's name, when loading a mod. +---@return string function core.get_current_modname() end ---- Returns the directory path for a mod, e.g. "/home/user/.minetest/usermods/modname". ---- - Returns nil if the mod is not enabled or does not exist (not installed). ---- - Works regardless of whether the mod has been loaded yet. ---- - Useful for loading additional `.lua` modules or static data from a mod, or checking if a mod is enabled. ---- @param mod_name string ---- @return string -function core.get_modpath(mod_name) end +---Returns the directory path for a mod, e.g. `"/home/user/.minetest/"` +---@param modname string +---@return string? +function core.get_modpath(modname) end ---- Returns a list of enabled mods, sorted alphabetically. ---- - Does not include disabled mods, even if they are installed. ---- @return table -function core.get_modnames() end +---Returns a list of the mods' names that are loaded or are yet to be loaded during startup. +---@param load_order boolean? +function core.get_modnames(load_order) end ---- @class GameInfo ---- @field id string ---- @field title string ---- @field author string ---- @field path string The root directory of the game. +---@class Core.GameInfo +---@field id string +---@field title string +---@field author string +---@field path string The root directory of the game. ---- Returns a table containing information about the current game. ---- Note that other meta information (e.g. version/release number) ---- can be manually read from `game.conf` in the game's root directory. +---Returns a table containing information about the current game. --- ---- @return GameInfo +---Note that other meta information (e.g. version/release number) +---can be manually read from game.conf in the game's root directory. +---@return Core.GameInfo function core.get_game_info() end ---- Returns e.g. "/home/user/.minetest/world" ---- - Useful for storing custom data ---- @return string +---Returns e.g. `"/home/user/.minetest/world"`. +---@return string function core.get_worldpath() end ---- Returns e.g. "/home/user/.minetest/mod_data/mymod" ---- - Useful for storing custom data independently of worlds. ---- - Must be called during mod load time. ---- - Can read or write to this directory at any time. ---- - It's possible that multiple Minetest instances are running at the same time, which may lead to corruption if you are not careful. ---- @return string +---Returns e.g. `"/home/user/.minetest/mod_data/mymod"` +---@return string function core.get_mod_data_path() end ---- @return boolean +---Returns `true` if the server is running in singleplayer mode, `false` otherwise. +---@return boolean function core.is_singleplayer() end +---@class Core.Features +---@field glasslike_framed boolean +---@field nodebox_as_selectionbox boolean +---@field get_all_craft_recipes_works boolean +---@field use_texture_alpha boolean +---@field no_legacy_abms boolean +---@field texture_names_parens boolean +---@field area_store_custom_ids boolean +---@field add_entity_with_staticdata boolean +---@field no_chat_message_prediction boolean +---@field object_use_texture_alpha boolean +---@field object_independent_selectionbox boolean +---@field httpfetch_binary_data boolean +---@field formspec_version_element boolean +---@field area_store_persistent_ids boolean +---@field pathfinder_works boolean +---@field object_step_has_moveresult boolean +---@field direct_velocity_on_players boolean +---@field use_texture_alpha_string_modes boolean +---@field degrotate_240_steps boolean +---@field abm_min_max_y boolean +---@field dynamic_add_media_table boolean +---@field particlespawner_tweenable boolean +---@field get_sky_as_table boolean +---@field get_light_data_buffer boolean +---@field mod_storage_on_disk boolean +---@field compress_zstd boolean +---@field sound_params_start_time boolean +---@field physics_overrides_v2 boolean +---@field hud_def_type_field boolean +---@field random_state_restore boolean +---@field after_order_expiry_registration boolean +---@field wallmounted_rotate boolean +---@field item_specific_pointabilities boolean +---@field blocking_pointability_type boolean +---@field dynamic_add_media_startup boolean +---@field dynamic_add_media_filepath boolean +---@field lsystem_decoration_type boolean +---@field item_meta_range boolean +---@field node_interaction_actor boolean +---@field moveresult_new_pos boolean +---@field override_item_remove_fields boolean +---@field hotbar_hud_element boolean +---@field bulk_lbms boolean +---@field abm_without_neighbors boolean +---@field biome_weights boolean +---@field particle_blend_clip boolean +---@field remove_item_match_meta boolean +---@field httpfetch_additional_methods boolean +---@field object_guids boolean +---@field on_timer_four_args boolean +---@field particlespawner_exclude_player boolean +---@field generate_decorations_biomes boolean +---@field chunksize_vector boolean +---@field item_image_animation boolean +---@field get_modnames_load_order boolean +---@field set_camera_resettable boolean +---@field hud_hideable_field boolean +---@field compress_raw_deflate boolean +---@field get_all_craft_recipes_fuel boolean +---@field get_all_craft_recipes_replacements boolean ---- Table containing API feature flags ---- @type table -core.features = { - --- @since 0.4.7 - glasslike_framed = true, - --- @since 0.4.7 - nodebox_as_selectionbox = true, - --- @since 0.4.7 - get_all_craft_recipes_works = true, - --- The transparency channel of textures can optionally be used on nodes - --- @since 0.4.7 - use_texture_alpha = true, - --- Tree and grass ABMs are no longer done from C++ - --- @since 0.4.8 - no_legacy_abms = true, - --- Texture grouping is possible using parentheses - --- @since 0.4.11 - texture_names_parens = true, - --- Unique Area ID for AreaStore:insert_area - --- @since 0.4.14 - area_store_custom_ids = true, - --- add_entity supports passing initial staticdata to on_activate - --- @since 0.4.16 - add_entity_with_staticdata = true, - --- Chat messages are no longer predicted - --- @since 0.4.16 - no_chat_message_prediction = true, - --- The transparency channel of textures can optionally be used on - --- objects (ie: players and lua entities) - --- @since 5.0.0 - object_use_texture_alpha = true, - --- Object selectionbox is settable independently from collisionbox - --- @since 5.0.0 - object_independent_selectionbox = true, - --- Specifies whether binary data can be uploaded or downloaded using the HTTP API - --- @since 5.1.0 - httpfetch_binary_data = true, - --- Whether formspec_version[] may be used - --- @since 5.1.0 - formspec_version_element = true, - --- Whether AreaStore's IDs are kept on save/load - --- @since 5.1.0 - area_store_persistent_ids = true, - --- Whether core.find_path is functional - --- @since 5.2.0 - pathfinder_works = true, - --- Whether Collision info is available to an objects' on_step - --- @since 5.3.0 - object_step_has_moveresult = true, - --- Whether get_velocity() and add_velocity() can be used on players - --- @since 5.4.0 - direct_velocity_on_players = true, - --- nodedef's use_texture_alpha accepts new string modes - --- @since 5.4.0 - use_texture_alpha_string_modes = true, - --- degrotate param2 rotates in units of 1.5° instead of 2° - --- thus changing the range of values from 0-179 to 0-240 - --- @since 5.5.0 - degrotate_240_steps = true, - --- ABM supports min_y and max_y fields in definition - --- @since 5.5.0 - abm_min_max_y = true, - --- dynamic_add_media supports passing a table with options - --- @since 5.5.0 - dynamic_add_media_table = true, - --- particlespawners support texpools and animation of properties, - --- particle textures support smooth fade and scale animations, and - --- sprite-sheet particle animations can by synced to the lifetime - --- of individual particles - --- @since 5.6.0 - particlespawner_tweenable = true, - --- allows get_sky to return a table instead of separate values - --- @since 5.6.0 - get_sky_as_table = true, - --- VoxelManip:get_light_data accepts an optional buffer argument - --- @since 5.7.0 - get_light_data_buffer = true, - --- When using a mod storage backend that is not "files" or "dummy", - --- the amount of data in mod storage is not constrained by - --- the amount of RAM available. - --- @since 5.7.0 - mod_storage_on_disk = true, - --- "zstd" method for compress/decompress - --- @since 5.7.0 - compress_zstd = true, - --- Sound parameter tables support start_time - --- @since 5.8.0 - sound_params_start_time = true, - --- New fields for set_physics_override: speed_climb, speed_crouch, - --- liquid_fluidity, liquid_fluidity_smooth, liquid_sink, - --- acceleration_default, acceleration_air - --- @since 5.8.0 - physics_overrides_v2 = true, - --- In HUD definitions the field `type` is used and `hud_elem_type` is deprecated - --- @since 5.9.0 - hud_def_type_field = true, - --- PseudoRandom and PcgRandom state is restorable - --- PseudoRandom has get_state method - --- PcgRandom has get_state and set_state methods - --- @since 5.9.0 - random_state_restore = true, - --- core.after guarantees that coexisting jobs are executed primarily - --- in order of expiry and secondarily in order of registration - --- @since 5.9.0 - after_order_expiry_registration = true, - --- wallmounted nodes mounted at floor or ceiling may additionally - --- be rotated by 90° with special param2 values - --- @since 5.9.0 - wallmounted_rotate = true, - --- Availability of the `pointabilities` property in the item definition - --- @since 5.9.0 - item_specific_pointabilities = true, - --- Nodes `pointable` property can be `"blocking"` - --- @since 5.9.0 - blocking_pointability_type = true, - --- dynamic_add_media can be called at startup when leaving callback as `nil` - --- @since 5.9.0 - dynamic_add_media_startup = true, - --- dynamic_add_media supports `filename` and `filedata` parameters - --- @since 5.9.0 - dynamic_add_media_filepath = true, - --- L-system decoration type - --- @since 5.9.0 - lsystem_decoration_type = true, - --- Overrideable pointing range using the itemstack meta key `"range"` - --- @since 5.9.0 - item_meta_range = true, - --- Allow passing an optional "actor" ObjectRef to the following functions: - --- core.place_node, core.dig_node, core.punch_node - --- @since 5.9.0 - node_interaction_actor = true, - --- "new_pos" field in entity moveresult - --- @since 5.9.0 - moveresult_new_pos = true, - --- Allow removing definition fields in `core.override_item` - override_item_remove_fields = true, -} +---Table containing server-side API feature flags. +---@type Core.Features +core.features = nil ---- Returns `boolean, missing_features` ---- * `arg`: string or table in format `{foo=true, bar=true}` ---- * `missing_features`: `{foo=true, bar=true}` ---- @param arg string|table ---- @return boolean,table +---Checks for server-side feature availability. +---@param arg string|table +---@return boolean +---@return table missing_features function core.has_feature(arg) end ---- Table containing information ---- about a player. Example return value: ---- ```lua ---- { ---- address = "127.0.0.1", -- IP address of client ---- ip_version = 4, -- IPv4 / IPv6 ---- connection_uptime = 200, -- seconds since client connected ---- protocol_version = 32, -- protocol version used by client ---- formspec_version = 2, -- supported formspec version ---- lang_code = "fr" -- Language code used for translation ---- -- the following keys can be missing if no stats have been collected yet ---- min_rtt = 0.01, -- minimum round trip time ---- max_rtt = 0.2, -- maximum round trip time ---- avg_rtt = 0.02, -- average round trip time ---- min_jitter = 0.01, -- minimum packet time jitter ---- max_jitter = 0.5, -- maximum packet time jitter ---- avg_jitter = 0.03, -- average packet time jitter ---- -- the following information is available in a debug build only!!! ---- -- DO NOT USE IN MODS ---- --ser_vers = 26, -- serialization version used by client ---- --major = 0, -- major version number ---- --minor = 4, -- minor version number ---- --patch = 10, -- patch version number ---- --vers_string = "0.4.9-git", -- full version string ---- --state = "Active" -- current client state ---- } ---- ``` ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4400-L4425) +---@class Core.PlayerInformation +---@field address string +---@field ip_version integer +---@field connection_uptime integer +---@field protocol_version integer +---@field formspec_version integer +---@field lang_code string +---@field min_rtt number? +---@field max_rtt number? +---@field avg_rtt number? +---@field min_jitter number? +---@field max_jitter number? +---@field avg_jitter number? +---@field version_string string +--- The following information is available in a debug build only!!! +-- -@field serialization_version integer? +-- -@field major integer? +-- -@field minor integer? +-- -@field patch integer? +-- -@field state string? + +---Table containing information about a player. +---@param player_name string +---@return Core.PlayerInformation function core.get_player_information(player_name) end +---Table mapping Luanti versions to corresponding protocol versions for modder convenience. +--- +---For example, to check whether a client has at least the feature set of Luanti 5.8.0 +---or newer, you could do: +---```lua +--- core.get_player_information(player_name).protocol_version >= core.protocol_versions["5.8.0"] +---``` +---@type table +core.protocol_versions = nil ---- Will only be present if the client sent this information (requires v5.7+) ---- ---- Note that none of these things are constant, they are likely to change during a client ---- connection as the player resizes the window and moves it between monitors ---- ---- real_gui_scaling and real_hud_scaling can be used instead of DPI. ---- OSes don't necessarily give the physical DPI, as they may allow user configuration. ---- real_*_scaling is just OS DPI / 96 but with another level of user configuration. ---- ```lua ---- { ---- -- Current size of the in-game render target (pixels). ---- -- ---- -- This is usually the window size, but may be smaller in certain situations, ---- -- such as side-by-side mode. ---- size = { ---- x = 1308, ---- y = 577, ---- }, ---- ---- -- Estimated maximum formspec size before Minetest will start shrinking the ---- -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than ---- -- this and `padding[-0.01,-0.01]`. ---- max_formspec_size = { ---- x = 20, ---- y = 11.25 ---- }, ---- ---- -- GUI Scaling multiplier ---- -- Equal to the setting `gui_scaling` multiplied by `dpi / 96` ---- real_gui_scaling = 1, ---- ---- -- HUD Scaling multiplier ---- -- Equal to the setting `hud_scaling` multiplied by `dpi / 96` ---- real_hud_scaling = 1, ---- ---- -- Whether the touchscreen controls are enabled. ---- -- Usually (but not always) `true` on Android. ---- -- Requires at least Minetest 5.9.0 on the client. For older clients, it ---- -- is always set to `false`. ---- touch_controls = false, ---- } ---- ``` +---@class Core.PlayerWindowInformation +---@field size {x:integer,y:integer} +---@field max_formspec_size {x:integer,y:integer} +---@field real_gui_scaling number +---@field real_hud_scaling number +---@field touch_controls boolean + +---@param player_name string +---@return Core.PlayerWindowInformation function core.get_player_window_information(player_name) end ---- Returns success. ---- * Creates a directory specified by `path`, creating parent directories ---- if they don't exist. +---Returns `true` if the given path exists else `false`. +---@param path string +---@return boolean +function core.path_exists(path) end + +---Creates a directory specified by path, creating parent directories if they don't exist. --- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4427-L4429) +---Returns success. +---@param path string +---@return boolean success function core.mkdir(path) end ---- Removes a directory specified by path. ---- If recursive is set to true, the directory is recursively removed. Otherwise, the directory will only be removed if it is empty. ---- Returns true on success, false on failure. ---- @param path string ---- @param recursive boolean ---- @return boolean +---Removes a directory specified by path. +--- +---If `recursive` is set to `true`, the directory is recursively removed. +---Otherwise, the directory will only be removed if it is empty. +---@param path string +---@param recursive boolean +---@return boolean success function core.rmdir(path, recursive) end - ---- Copies a directory specified by path to destination ---- Any files in destination will be overwritten if they already exist. ---- Returns true on success, false on failure. ---- @param source string ---- @param destination string ---- @return boolean +---Copies a directory specified by source to destination. +--- +---Any files in `destination` will be overwritten if they already exist. +---@param source string +---@param destination string +---@return boolean success function core.cpdir(source, destination) end - ---- Moves a directory specified by path to destination. ---- If the destination is a non-empty directory, then the move will fail. ---- Returns true on success, false on failure. ---- @param source string ---- @param destination string ---- @return boolean +---Moves a directory specified by source to destination. +--- +---If the `destination` is a non-empty directory, then the move will fail. +--- @param source string +--- @param destination string +--- @return boolean success function core.mvdir(source, destination) end ---- Returns list of entry names ---- * `is_dir` [Optional] is one of: ---- * nil: return all entries, ---- * true: return only subdirectory names, or ---- * false: return only file names. ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4430-L4434) +---Returns list of entry names +---@param path string +---@param is_dir boolean? is one of: +--- * `nil`: return all entries +--- * `true`: return only subdirectory names +--- * `false`: return only file names +---@return string[] function core.get_dir_list(path, is_dir) end ---- Returns boolean indicating success ---- * Replaces contents of file at path with new contents in a safe (atomic) ---- way. Use this instead of below code when writing e.g. database files: ---- `local f = io.open(path, "wb"); f:write(content); f:close()` +---Replaces contents of file at path with new contents in a safe (atomic) way. --- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4435-L4438) +---Use this instead of below code when writing e.g. database files: +---```lua +--- local f = io.open(path, "wb"); f:write(content); f:close() +---``` +---@param path string +---@param content string function core.safe_file_write(path, content) end ---- Returns a table containing components of the ---- engine version. Components: ---- * `project`: Name of the project, eg, "Minetest" ---- * `string`: Simple version, eg, "1.2.3-dev" ---- * `hash`: Full git version (only set if available), ---- eg, "1.2.3-dev-01234567-dirty". ---- Use this for informational purposes only. The information in the returned ---- table does not represent the capabilities of the engine, nor is it ---- reliable or verifiable. Compatible forks will have a different name and ---- version entirely. To check for the presence of engine features, test ---- whether the functions exported by the wanted features exist. For example: ---- `if core.check_for_falling then ... end`. ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4439-L4450) +---@class Core.Version +---@field project string +---@field string string +---@field proto_min integer +---@field proto_max integer +---@field hash string +---@field is_dev string + +---Returns a table containing components of the engine version. +---@return Core.Version function core.get_version() end ---- Returns the sha1 hash of data ---- * `data`: string of data to hash ---- * `raw`: [Optional] return raw bytes instead of hex digits, default: false ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4451-L4453) +---Returns the sha1 hash of data. +---@param data string string of data to hash +---@param raw boolean? return raw bytes instead of hex digits, default: `false` +---@return string function core.sha1(data, raw) end ---- Returns the sha256 hash of `data` ---- @param data string string of data to hash ---- @param raw boolean optional. return raw bytes instead of hex digits, default: false +---Returns the sha256 hash of data +---@param data string string of data to hash +---@param raw boolean? return raw bytes instead of hex digits, default: `false` +---@return string function core.sha256(data, raw) end ---- Converts a ColorSpec to a ColorString. If the ColorSpec is invalid, returns `nil`. ---- @param colorspec ColorSpec The ColorSpec to convert. ---- @return ColorString? +---Converts a `ColorSpec` to a `ColorString`. +--- +---If the ColorSpec is invalid, returns `nil`. +---@param colorspec ColorSpec +---@return ColorString? function core.colorspec_to_colorstring(colorspec) end ---- Converts a ColorSpec to a raw string of four bytes in an RGBA layout, returned as a string. ---- @param colorspec ColorSpec The ColorSpec to convert. ---- @return string? +---Converts a `ColorSpec` to a raw string of four bytes in an RGBA layout, +---returned as a string. +---@param colorspec ColorSpec +---@return string? function core.colorspec_to_bytes(colorspec) end ---- Converts a ColorSpec into RGBA table form. If the ColorSpec is invalid, returns nil. You can use this to parse ColorStrings. ---- @param colorspec ColorSpec The ColorSpec to convert. ---- @return {r:number, g:number, b:number, a:number}? +---Converts a `ColorSpec` into RGBA table form. +--- +---If the ColorSpec is invalid, returns `nil`. You can use this to parse `ColorStrings`. +---@param colorspec ColorSpec +---@return ColorTable? function core.colorspec_to_table(colorspec) end + +---Returns a `"day-night ratio"` value (as accepted by `ObjectRef:override_day_night_ratio`) +---that is equivalent to the given `"time of day"` value (as returned by `core.get_timeofday`). +---@param time_of_day number? +function core.time_to_day_night_ratio(time_of_day) end + +---Encode a PNG image and return it in string form. +---@param width integer Width of the image (integer in range [u32]) +---@param height integer Height of the image (integer in range [u32]) +---@param data table Image data, one of: +--- * array table of ColorSpec, length must be `width*height` +--- * string with raw RGBA pixels, length must be `width*height*4` +---@param compression integer? Optional zlib compression level, integer in range [0, 9]. +--- The data is one-dimensional, starting in the upper left +--- corner of the image and laid out in scanlines going from +--- left to right, then top to bottom. +--- You can use colorspec_to_bytes to generate raw RGBA values. +--- Palettes are not supported at the moment. You may use this +--- to procedurally generate textures during server init. +---@return string +function core.encode_png(width, height, data, compression) end + +---Encodes reserved URI characters by a percent sign followed by two hex digits. +--- +---See [RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3). +---@param str string +function core.urlencode(str) end diff --git a/specs/Color.lua b/specs/Color.lua index f480c86..de28c05 100644 --- a/specs/Color.lua +++ b/specs/Color.lua @@ -1,22 +1,33 @@ ---- @meta +---Version: 5.18 +---@meta +--- Colors --- ---- A ColorString is a string that represents a color. It can be one of the following: ---- * a named color, e.g. `"red"`, `"blue"`, `"green"`, etc. ---- (see [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-colors) for a full list of named colors) ---- * a named color with alpha, e.g. `"red#08"`, `"blue#FF"`, `"green#F"`, etc. ---- * an RGB or RGBA hex color code, e.g. `"#RRGGBB"` or `"#RRGGBBAA"`, where `RR`, `GG`, `BB`, and `AA` are two-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. ---- * e.g. `"#FF0000"` for red, `"#00FF00"` for green, `"#0000FF"` for blue, etc. ---- * a shorthand hex color code, e.g. `"#RGB"` or `"#RGBA"`, where `R`, `G`, `B`, and `A` are single-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. ---- @alias ColorString string +--- * `"#RGB"` defines a color in hexadecimal format, fully opaque. +--- * `"#RGBA"` defines a color in hexadecimal format, with an alpha channel. +--- * `"#RRGGBB"` defines a color in hexadecimal format, fully opaque. +--- * `"#RRGGBBAA"` defines a color in hexadecimal format, with an alpha channel. +--- +---Named colors are also supported and are equivalent to +---[CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-color). +---To specify the value of the alpha channel, +---append `#A` or `#AA` to the end of the color name (e.g. `"darkgreen#08"`). +---@alias ColorString string +---@class ColorTable +---@field r integer +---@field g integer +---@field b integer +---@field a integer - ---- A ColorSpec specifies a 32-bit color. It can be written in any of the following forms: ---- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255): ---- `colorspec = {a=255, r=0, g=255, b=0}` ---- * numerical form: The raw integer value of an ARGB8 quad: ---- `colorspec = 0xFF00FF00` ---- * string form: A ColorString (defined above): ---- `colorspec = "green"` ---- @alias ColorSpec {r:number, g:number, b:number, a:number}|ColorString|number +---A ColorSpec specifies a 32-bit color. It can be written in any of the following forms: +--- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255): +--- +--- `colorspec = {a=255, r=0, g=255, b=0}` +--- * numerical form: The raw integer value of an ARGB8 quad: +--- +--- `colorspec = 0xFF00FF00` +--- * string form: A ColorString (defined above): +--- +--- `colorspec = "green"` +---@alias ColorSpec ColorTable|ColorString|integer