API Core Utilities

API: Core Utilities

This reference applies to PleasureLib 0.5.0. Examples assume a runtime named pleasureLib; see Getting Started.

The library table exposes its current version as PleasureLib.VERSION and the runtime constructor as PleasureLib.new.

Constructor

PleasureLib.new(options)

Creates a new per-mod runtime.

Option	Type	Description
mod or mod_name	string	Log prefix; defaults to PleasureLib.
debug	boolean	Enables debug logging only when exactly true.

local runtime = PleasureLib.new({
    mod = "MyMod",
    debug = false,
})

The returned table exposes mod_name, object_cache, and all runtime methods.

Logging and protected calls

runtime:log(message)

Prints a UE4SS log line prefixed with the runtime mod name.

runtime:set_debug(value)

Enables debug logging when value == true; disables it otherwise.

runtime:debug_log(message)

Calls log with a [debug] marker only when debug mode is enabled.

runtime:safe(label, fn)

Runs fn through pcall. Returns the function result on success. On failure, logs a readable error with label and returns nil.

local value = pleasureLib:safe("read player name", function()
    return player:GetName()
end)

runtime:try(fn)

Runs fn through pcall. Returns the function result on success or nil on failure without logging.

Strings and config

runtime:trim(value)

Converts value to a string and removes leading and trailing whitespace.

runtime:lower(value) / runtime:upper(value)

Trims value, then returns its lowercase or uppercase representation.

runtime:parse_bool(value, default)

Parses common boolean strings after trimming and lowercasing.

Result	Accepted values
true	true, 1, yes, on
false	false, 0, no, off
default	Empty or unknown values

runtime:parse_ini(content)

Parses simple KEY=value content into a table with uppercase keys. Blank lines, section headers, and lines beginning with ; or # are ignored.

local config = pleasureLib:parse_ini([[
Enabled=true
Items=A; B; C
]])

local enabled = pleasureLib:parse_bool(config.ENABLED, false)

This is intentionally a small parser. It does not preserve sections or comments in the returned table.

runtime:split_list(value, separator_pattern)

Splits a string into a trimmed array. The default separator pattern is a semicolon. Pass a Lua pattern to use a different separator.

local entries = pleasureLib:split_list("A; B; C")

runtime:copy_array(values)

Returns a shallow array copy using ipairs. Non-array keys are not copied.

Files

runtime:script_directory(stack_level)

Returns the directory of the calling Lua file, including its trailing slash. When used as a normal instance method, no argument is needed. Returns nil when debug source information is unavailable.

runtime:read_text_file(path)

Reads the complete text file. Returns its content or nil when it cannot be opened.

runtime:write_text_file(path, content)

Writes content to path, replacing existing content. Returns true on success and false on failure.

runtime:update_ini_value(path, key, value)

Updates the first matching key=value line without discarding other lines or comments. Key comparison is case-insensitive. Appends the key when no matching line exists. Returns true on success.

pleasureLib:update_ini_value(config_path, "Enabled", "true")

Static exports

The library table exposes these stateless helpers directly:

PleasureLib.noop
PleasureLib.try
PleasureLib.trim
PleasureLib.lower
PleasureLib.upper
PleasureLib.parse_bool
PleasureLib.parse_ini
PleasureLib.split_list
PleasureLib.copy_array
PleasureLib.unwrap
PleasureLib.is_valid
PleasureLib.safe_to_string
PleasureLib.full_name
PleasureLib.script_directory
PleasureLib.read_text_file
PleasureLib.write_text_file
PleasureLib.update_ini_value

Normal mod code should prefer an instance from PleasureLib.new(...) so logging and the object cache remain scoped to the consuming mod.