Luka's Scripting Utilities

A pack full of various scripting utilities to ease your development!

v4.1.135,194

Ruby Object Extensions

LUTS adds a set of convenience methods to the Ruby built-in classes. The most
widely used are the blank? / present? predicates, which are defined
consistently across Array, Hash, String, Numeric, Symbol and
NilClass so you can test "emptiness" uniformly regardless of type.

Array

array.swap_at(index1, index2) swaps the values at two indexes
array.to_last(val) moves a value to the end of the array (removing it from its current position first)
array.last?(index) checks whether the given index is the last index
array.string_include?(val) checks whether any string element is contained within the given string
array.value(index) fetches the element at the given index
array.blank? true when the array has no elements
array.present? true when the array has any elements

Hash

hash.value(key) returns the value for the given key
hash.merge_many(*hashes) merges multiple hashes into self
hash.blank? true when the hash has no keys
hash.present? true when the hash has any keys

String

Constants & casing

string.constantize resolves the string to a Ruby constant (object)
string.safe_constantize resolves to a constant, or nil if it does not exist
string.capitalize capitalises the first letter
string.camelize converts an under_scored string to CamelCase
string.underscore converts a CamelCased string to snake_case
string.demodulize strips leading module namespaces from a constant name
string.preposition returns the indefinite article ("a" or "an") for the string
string.blank? true when the string is empty or only whitespace
string.present? true when the string has non-whitespace content

Console colour tags

These wrap the string in colour markup for console output:

string.red · string.green · string.blue ·
string.cyan · string.magenta · string.yellow ·
string.purple · string.orange

Numeric

number.lerp(inverse: false) scales the number for frame-rate-independent interpolation
number.blank? true when the value is zero
number.present? true when the value is non-zero

Frame-count helpers convert a count into the equivalent number of 60-FPS frames
(singular forms are aliases of the plural):

number.minute / number.minutes
number.hour / number.hours
number.day / number.days

# wait two in-game minutes (in frames)
2.minutes   # => 7200

Symbol & NilClass

For interface consistency with the other types:

symbol.blank? always false, symbol.present? always true
nil.blank? always true, nil.present? always false

Graphics Object Extensions

LUTS reopens the core graphics classes — Color, Tone, Rect, Sprite,
Viewport and Graphics — to add helpers and to mix in the animation, float
and shader concerns. Because the concerns are already included, every object of
these types can be animated, given a shader, or queried for its on-screen
position without any extra setup.

Color

Includes LUTS::Concerns::Animatable, so colours can be tweened.

Color.blank a fully transparent black (all components zero)
Color.dark_gray a dark gray preset (64, 64, 64)
color.darken(amt = 0.2) returns a darkened copy of the colour
color.blank? true when every component (R, G, B, A) is zero
color.present? true when any component is non-zero
color.to_vec3 normalised [r, g, b] floats (0.0–1.0), e.g. for shader uniforms
color.to_vec4 normalised [r, g, b, a] floats (0.0–1.0)

Tone

Includes LUTS::Concerns::Animatable.

tone.lookup_table a memoised Tone::LookupTable for fast per-channel pixel transforms
tone.all the average of the red, green and blue channels
tone.all = val sets all three colour channels at once

The nested Tone::LookupTable precomputes the channel mapping and
grayscale mix for a tone (using the standard YUV luma weights) so it can
transform(r, g, b) pixels efficiently — this is what Bitmap#apply_tone
uses.

Rect

Includes LUTS::Concerns::Animatable and
LUTS::Concerns::Floatable, so a rect's components can be animated
and tracked as floats.

Sprite

Includes Animatable, Floatable and
Shaderable. Adds viewport-aware geometry helpers:

sprite.in_viewport? true when the sprite is visible within its viewport (64-pixel margin)
sprite.apparent_x / sprite.apparent_y on-screen position accounting for origin and zoom
sprite.apparent_width / sprite.apparent_height on-screen size accounting for zoom

(See the Sprites section for the much larger Sprites::Base subclass.)

Viewport

Includes Animatable, Floatable, Shaderable
and BlockConstructor. Adds tagging, sprite enumeration and direct
geometry accessors.

Tagging

Viewport.get_by_tag(tag) all viewports carrying the given tag
viewport.tag = value adds a tag to the viewport
viewport.tags the list of assigned tags
viewport.tag?(tag) whether the viewport carries a tag

Sprites & compositing

viewport.sprites all non-disposed sprites in the viewport, sorted by z
viewport.flatten renders all visible sprites into a single Bitmap
viewport.reset_color clears any applied colour (sets it to blank)

Geometry & colour

Direct passthroughs to the underlying rect / colour so you don't have to reach
through .rect: viewport.x, viewport.y,
viewport.width, viewport.height and
viewport.alpha — each with a matching = writer.

Graphics

Adds a global animation driver used by the Animatable concern:

Graphics.animate(duration, &block) runs the block, then plays the registered animations of every cached object across duration frames, cleaning the cache up afterwards
Graphics.target_object_cache the list of objects queued for animation

Graphics.animate(20) do
  @sprite.animate(x: 320, opacity: 255)
  @other.animate(zoom_x: 2.0)
end

Filesystem & Environment

Helpers for working with files, directories and well-known system paths.

File

File.safe_data?(file) safely checks whether a .rxdata file exists and is loadable (it attempts the load and returns a boolean rather than raising)

Dir

Dir.create(path) recursively creates every directory needed for a path
Dir.all_dirs(path) walks a directory tree and returns every directory found within it
Dir.delete_all(path) deletes all files in a directory and its subdirectories (works on non-empty directories)

Env

Env resolves well-known Windows directories by GUID and escapes reserved
filesystem characters.

Env.path(type) resolves a known directory path from its key (e.g. 'DESKTOP', 'DOCUMENTS', 'DOWNLOADS')
Env.directory the current working directory of the game
Env.guid_to_hex(string) converts a GUID string to the hex array format the OS expects
Env.char_esc(string) escapes reserved filesystem characters in place
Env.char_dsc(string) restores previously escaped characters in place

Known path keys (`COMMON_PATHS`)

CAMERA_ROLL, START_MENU, DESKTOP, DOCUMENTS, DOWNLOADS, HOME,
MUSIC, PICTURES, SAVED_GAMES, SCREENSHOTS, VIDEOS, LOCAL,
LOCALLOW, ROAMING, PROGRAM_DATA, PROGRAM_FILES_X64,
PROGRAM_FILES_X86, COMMON_FILES, PUBLIC.

desktop = Env.path('DESKTOP')
Dir.create(desktop + '/MyGame/exports/')

The reserved characters handled by char_esc / char_dsc are
\ / : * ? ' < > |.

Animatable

LUTS::Concerns::Animatable lets you tween any numeric property of an object
towards a target value. It is already included in Sprite, Viewport,
Color, Tone and Rect, so you can animate those directly. To make your own
class animatable, include LUTS::Concerns::Animatable.

How it works

You register the target values you want with animate, then let
Graphics.animate drive the tween over a number of frames. The
object is queued in Graphics.target_object_cache and each registered property
is advanced every frame (using frame-rate-independent lerp interpolation)
until the duration elapses.

Graphics.animate(30) do          # tween over 30 frames
  @sprite.animate(x: 400, y: 120, opacity: 0)
end

API

object.animate(options) registers properties → target values to tween (a Hash like { x: 400, opacity: 0 }). Ignored if the object is already animating.
object.animating? whether any animation targets are currently registered
object.anim_target the registered targets (each stored with its interpolation state)
object.play_target_animation(duration) advances every registered property one step towards its target over duration frames — normally called for you by Graphics.animate
object.clear_anim_target clears all registered animation values

QuickAnimatable

LUTS::QuickAnimatable is a higher-level, declarative layer for sprite-group
animations. Include it in a class that exposes sprites, viewport and
update, then describe the animation as an array of steps.

Each step is [duration, { sprite_key => { attribute => value } }]:

class MyScene
  include LUTS::QuickAnimatable

  def quick_animation_array
    [
      [20, { logo: { opacity: 255, y: 100 } }],
      [10, { logo: { zoom_x: 1.2, zoom_y: 1.2 } }]
    ]
  end
end

play_quick_animation plays every step in quick_animation_array in sequence, calling animate on the named sprites
quick_animation_array (you implement this) returns the list of animation steps; raises NotImplementedError if missing

The concern validates at runtime that the host class provides sprites,
viewport and update before playing.

Floatable & Shaderable

Floatable

LUTS::Concerns::Floatable adds sub-pixel float tracking to an object. RGSS
properties like x, y and opacity are integers, which makes slow or
fractional movement stutter. Floatable keeps a parallel set of float values
and writes the rounded result back to the object.

It is already included in Sprite, Viewport and Rect. To add it yourself,
include LUTS::Concerns::Floatable.

object.float returns the object's FloatValues wrapper (created on first use)

FloatValues

FloatValues tracks these properties as floats and pushes each change back to
the wrapped object when it responds to the matching setter:

x · y · ox · oy ·
width · height · opacity ·
angle

Each has a getter and a setter (e.g. float.x / float.x = 1.5).

@sprite.float.x += 0.4   # accumulates; the sprite's integer x updates when it crosses a pixel

Shaderable

LUTS::Concerns::Shaderable manages a stack of GLSL shaders on an object. It is
already included in Sprite and Viewport (both of which expose a writable
shaders array).

object.add_shader(key, properties = {}) adds a shader — pass a Symbol key to load a new Shader (with optional uniform properties), or pass an existing Shader instance
object.get_shader(key) fetches an applied shader by its key symbol or by array index
object.remove_shader(key) removes a shader by key symbol, index, or instance
object.dispose_shaders disposes every applied shader and clears the stack

@sprite.add_shader(:wave, intensity: 0.5)
@sprite.get_shader(:wave)
@sprite.remove_shader(:wave)

The Shader class

Shader.new(key, properties = {}) loads the GLSL file at
Data/Shaders/{key}.glsl and applies the given uniform properties. Uniform
values may be bitmaps, strings, or numeric vectors of 1–4 components (so a
Color#to_vec4 works directly). It raises Shader::ShaderError if the shader
file does not exist.

shader.key the shader's identifier symbol
shader.dispose / shader.disposed? standard disposal lifecycle

BlockConstructor

LUTS::Concerns::BlockConstructor lets a class accept a configuration block in
its constructor — a built-in alternative to .tap. After the normal
initialisation runs, the new instance is yielded to the block.

Viewport.new(0, 0, 640, 480) do |vp|
  vp.z = 9999
  vp.tag = :overlay
end

Viewport already includes this concern; include
LUTS::Concerns::BlockConstructor in your own class to gain the behaviour.

Helper Classes

Two small base classes used throughout LUTS for declaring data and deferring
callbacks.

AttributeContainer

AttributeContainer is a base class for objects that declare a fixed set of
attributes with default values. Subclass it and register attributes; each one
gets a reader, a writer, and — when the default is a boolean — a ? predicate.

class Settings < AttributeContainer
  with_attribute :volume, default: 100
  with_attribute :muted,  default: false
end

s = Settings.new
s.volume        # => 100
s.muted?        # => false  (predicate, because the default is boolean)
s.volume = 50

SubClass.with_attribute(key, default: nil) declares an attribute (and its predicate, for booleans)
SubClass.attribute_list the registered attributes mapped to their defaults
SubClass.new initialises every attribute to its default value

Attribute definitions are inherited by further subclasses.

CallbackWrapper

CallbackWrapper stores a block and executes it later in an isolated context,
with keyword params exposed inside the block as instance variables.

cb = CallbackWrapper.with_params(name: "Pikachu") { puts @name }
cb.execute                       # prints "Pikachu"

# equivalent long form:
cb = CallbackWrapper.new { puts @name }
cb.set_params(name: "Pikachu")
cb.execute

CallbackWrapper.with_params(**kwargs, &block) builds a wrapper and immediately sets its params
wrapper.set_params(**kwargs) exposes the given keywords as instance variables in the block context (chainable — returns self)
wrapper.execute runs the block in the isolated context and returns its result (or nil if no block was given)

Sprites::Base

Sprites::Base is the workhorse sprite class for LUTS-based plugins. It
subclasses the core Sprite (so it inherits the Animatable, Floatable and
Shaderable behaviour) and layers on a large toolkit of bitmap, colour and
positioning helpers.

sprite = Sprites::Base.new(viewport) do |s|
  s.set_bitmap("Graphics/Pictures/logo")
  s.center!(snap: true)
end

Sprites::Base.new(viewport, &block) creates the sprite, seeds its default
attributes, and yields itself to an optional configuration block.

Extra attributes

Beyond the standard sprite properties, Sprites::Base carries a set of
free-use accessors that the various plugins lean on: direction, speed,
toggle, end_x, end_y, param, skew_d, ex, ey, zx, zy, dx,
dy, finished, plus the read-only stored_bitmap. Call default!
to reset them.

Dimensions

sprite.width / sprite.width = val source-rect width
sprite.height / sprite.height = val source-rect height
sprite.zoom / sprite.zoom = val uniform zoom on both axes

Bitmaps

sprite.set_bitmap(bmp) set the bitmap from a path or a bitmap object
sprite.create_rect(width, height, color) set the bitmap to a solid colour rect
sprite.full_rect(color) fill the whole screen with a colour
sprite.blank_screen set a blank bitmap the size of the viewport
sprite.snap_screen capture a screenshot as the bitmap
sprite.stretch_screen(path) draw a bitmap stretched across the whole screen
sprite.memorize_bitmap(bmp = nil) remember the current (or given) bitmap
sprite.restore_bitmap restore the memorised bitmap
sprite.online_bitmap(url) download and apply a bitmap from a URL
sprite.mask(mask = nil, ox: 0, oy: 0) mask the bitmap with another bitmap
sprite.text_sprite(width = viewport.width, height = viewport.height) create a bitmap with the system font applied, ready for text

Colour effects

sprite.alpha / sprite.alpha = val the colour's alpha channel
sprite.swap_colors(map) swap the colour palette using a colour-map bitmap
sprite.avg_color(freq: 2) the average colour of the bitmap (sampling every freq pixels)
sprite.blur blur the sprite
sprite.outline(color) draw an outline
sprite.colorize(color, amount: 255) tint the solid pixels by amount (0–255)
sprite.glow(color, keep: true) draw a glow; keep: false drops the original bitmap

Positioning

sprite.center the [x, y] of the sprite's centre point
sprite.center!(snap: false) centre the sprite on itself, or on the viewport with snap: true
sprite.bottom the [x, y] of the bottom-centre point
sprite.bottom! anchor the sprite to its bottom centre
sprite.anchor(type) set the origin to a named anchor

Anchor types: :top_left, :top_middle, :top_right, :middle_left,
:middle, :middle_right, :bottom_left, :bottom_middle, :bottom_right.

Special Sprites

Several ready-made Sprites::Base subclasses cover common animated-sprite
needs. Each one renders itself when you call update every frame.

Sprites::Scrolling

A sprite whose bitmap scrolls continuously — useful for backgrounds, conveyor
belts and parallax. Optionally pulses its opacity while scrolling.

scrolling.set_bitmap(path, vertical: false, pulse: false, speed: @speed) set the scrolling bitmap (returns self for chaining)
scrolling.update advance the scroll one frame

Accessors: speed, direction, vertical, pulse, min_o, max_o,
current_x, current_y.

bg = Sprites::Scrolling.new(viewport).set_bitmap("clouds", speed: 1.5)
# in the update loop:
bg.update

Sprites::Rainbow

A sprite that cycles its hue over time for a shifting rainbow effect.

rainbow.set_bitmap(path, speed: 1) set the bitmap and the per-frame hue-shift speed
rainbow.update advance the hue one frame

Sprites::Sheet

A spritesheet animator that steps through evenly divided frames of a sheet.

sheet.set_bitmap(file, frames: 1, vertical: false, speed: @speed) load a sheet of frames frames (laid out horizontally, or vertically with vertical: true); speed is the number of update ticks per frame
sheet.update advance the animation one tick
sheet.cur_frame the current frame index (read-only); sheet.speed ticks per frame

AnimatedPlane

AnimatedPlane is a Plane subclass that adds end_x / end_y accessors so a
scrolling plane's target offset can be tracked by the animation system.

SpriteHash

SpriteHash is a manager that owns a keyed collection of sprites sharing one
viewport. It handles construction, iteration, bulk updates and disposal, so a
scene can keep all its sprites in a single object.

@sprites = SpriteHash.new(viewport)

@sprites.add(:logo, bitmap: "Graphics/Pictures/logo")
@sprites.add(:bar, type: :Scrolling) do |s|
  s.set_bitmap("loadbar", speed: 2)
end

# every frame:
@sprites.update

# when done:
@sprites.dispose

Adding sprites

hash.add(key, options = {}, &block) build and store a sprite under key, yielding it to the block. Recognised options:
- :type a Sprites::* type symbol (e.g. :Scrolling, :Rainbow, :Sheet)
- :class an explicit sprite class (overrides :type)
- :object a pre-built sprite object to adopt
- :bitmap a path string, or a hash with a :file key plus extra options
hash.add_raw(key, object, &block) store a sprite instantiated elsewhere

Access & iteration

hash[key] fetch a sprite by key
hash.keys all keys · hash.key?(key) whether a key exists
hash.each { |key, sprite| } iterate key/sprite pairs
hash.each_sprite { |sprite| } iterate sprites
hash.each_key { |key| } iterate keys
hash.select { |key, sprite| } / hash.reject { |key, sprite| } filter

Bulk operations

hash.update update every sprite in the collection
hash.set(options = {}) assign an attribute on every sprite (e.g. set(opacity: 0))
hash.viewport = vp reassign the viewport across all sprites
hash.dispose(options = {}) dispose all sprites; supports :only / :except key filters
hash.disposed? whether the collection is empty

Bitmap helpers

Class methods for resolving bitmaps used internally and available directly:

SpriteHash.bitmap(path) resolve a bitmap from a path or any bitmap-able object
SpriteHash.online_bitmap(url) download and return a bitmap (nil if the downloaded file is unsafe)

Bitmap Drawing

Sprites::Bitmap is a Bitmap subclass with higher-level drawing helpers for
text, shapes, masking and colour work. It can be created with the usual bitmap
arguments (a size or a file path) and accepts a configuration block.

bmp = Sprites::Bitmap.new("Graphics/Pictures/panel")
bmp.render_text("Hello", x: 8, y: 8, base: Color.white, outline: true)

It tracks the path it was loaded from (bitmap.path).

Text

bitmap.set_font(name:, size:, bold: false) set the font for subsequent text rendering
bitmap.render_text(text, x:, y:, align: :left, base: Color.white, shadow: Color.dark_gray, outline: false) draw a single line of text with shadow / optional outline; align is :left, :center or :right
bitmap.render_text_ex(text, x:, y:, width:, lines:, line_height: 32, base: Color.white, shadow: Color.dark_gray) draw word-wrapped text within a bounded box of lines lines

Shapes

bitmap.draw_circle(color, radius:, hollow: false) draw a filled (or, with hollow: true, outlined) circle

Colour & masking

bitmap.mask!(mask = nil, offset_x: 0, offset_y: 0) apply a mask using the alpha channel of another image — the mask may be a Bitmap, a Sprite, or a file-path String
bitmap.swap_colors(bmp) remap colours using a map bitmap whose first row lists source colours and second row lists target colours
bitmap.apply_tone(tone) apply a Tone directly to the pixel data (via the tone's lookup table)
bitmap.tolerance?(pixel, target) whether a pixel matches a target colour within tolerance
bitmap.finished? always true (bitmaps have no inherent animation; provided for interface parity)

Polygon rendering

Bitmaps::Polygon is a Bitmap subclass that draws a filled polygon from a
list of vertices using an optimised scanline fill. Create it with a size, add
vertices, then render.

poly = Bitmaps::Polygon.new(128, 128)
5.times { |i| poly.calc_vertex(percent: 1.0, angle: i * 72) }   # a pentagon
poly.render(Color.new(255, 80, 80))

polygon.add_vertex(x:, y:) add a vertex at an absolute point
polygon.calc_vertex(percent:, angle:) add a vertex by polar coordinates — percent of the bitmap radius at angle degrees from centre
polygon.render(color = Color.black) fill the polygon (needs at least 3 vertices)

Mouse Input

The Mouse module wraps mkxp-z mouse handling into a friendly API, and extends
Sprite, Viewport and Rect with hit-testing and dragging helpers. A press
counts as a click when it is released within Mouse::CLICK_TIMEOUT (0.5 s).

All button arguments accept :left (default), :right or :middle.

Cursor state

Mouse.active? whether the cursor is inside the game window
Mouse.show / Mouse.hide show or hide the system cursor

Buttons

Mouse.click?(button = :left) pressed and released within the click timeout
Mouse.press?(button = :left) currently pressed
Mouse.release?(button = :left) just released
Mouse.repeat?(button = :left) input is repeating
Mouse.hold?(button) held longer than the click timeout

Wheel

Mouse.scroll_up?(rect = nil) wheel scrolled up (optionally only while over rect)
Mouse.scroll_down?(rect = nil) wheel scrolled down (optionally only while over rect)

Hit testing

Mouse.over?(object) whether the cursor is over an object (the object must respond to mouse_params)
Mouse.over_area?(x, y, w, h) whether the cursor is within an arbitrary rectangle
Mouse.create_rect(button = :left) build a Rect from a click-and-drag selection (empty when not dragging)

Dragging

Mouse.dragging?(object, button = :left) whether the object is currently being dragged
Mouse.drag_object(object, button = :left, rect = nil, lock = nil) drag the object to follow the cursor, optionally bounded by rect and locked to :horizontal or :vertical
Mouse.drag_object_x(object, ...) / Mouse.drag_object_y(object, ...) drag on one axis only

Object extensions

Sprite, Viewport and Rect gain the following (each computes its own
on-screen mouse_params):

object.over? cursor is over the object
object.click? object was clicked
object.press? mouse is pressed over the object
object.mouse_drag(rect = nil) drag with the left button (also mouse_drag_x / mouse_drag_y)
object.overlap?(target) this object's area overlaps the target's
object.released_in?(target) mouse released while overlapping the target
object.released_in_rect?(target) mouse released while this object's position falls inside the target rect

Sprites additionally provide:

sprite.over_pixel? cursor is over a non-transparent pixel (alpha-aware hit testing)

if @button.click?
  do_thing
elsif @icon.over_pixel?
  @icon.colorize(Color.yellow, amount: 80)
end

Barcode Generator

BarcodeGenerator renders a UPC-A barcode to a Bitmap from a numeric
value of up to 11 digits. The 12th check digit is calculated for you, and the
input is zero-padded to the full width.

bmp = BarcodeGenerator.new(12345).generate
sprite.bitmap = bmp

Usage

BarcodeGenerator.new(number, height: 96, unit: 4, color_white: ..., color_black: ...)

number the value to encode (Integer, ≤ 11 digits)
height bar height in pixels (default 96)
unit bar unit width in pixels (default 4)
color_white / color_black the two bar colours (default white / black)

Then:

generator.generate the full UPC-A barcode bitmap — guards, both digit halves and the check digit
generator.generate_trimmed a trimmed bitmap containing only the right-hand 5 digits, for tight layouts

Errors

BarcodeGenerator::TypeError — the input was not an Integer
BarcodeGenerator::SizeError — the input had more than 11 digits

Both generate and generate_trimmed return a standard Bitmap you can
assign to any sprite.

QR Code Generator

QRCodeGenerator encodes an arbitrary string into a scannable QR code Bitmap
using byte-mode encoding with full Reed-Solomon error correction.

bmp = QRCodeGenerator.new("https://luka-sj.com").generate
sprite.bitmap = bmp

Usage

QRCodeGenerator.new(data, version: nil, unit_size: 4, color_white: ..., color_black: ...)

data the string to encode
version the QR version (size). Leave nil to auto-select the smallest version that fits
unit_size pixel size of each module (default 4)
color_white / color_black the module colours (default white / black)

Then:

generator.generate renders the final QR bitmap, including the 4-module quiet-zone border

Choosing a version

QRCodeGenerator.recommend_version(data, mode = :byte) the smallest supported version that fits the data (or nil)
QRCodeGenerator.version_capacity(version, mode = :byte) the approximate byte capacity of a version

Supported range

Versions 2–4 only (version 1 is not supported).
Byte mode encoding (any string data).
Error correction level L (≈ 7% recovery).

If the data exceeds the capacity of all supported versions — or an explicit
version: is out of range — construction raises ArgumentError.

Internals

The generator is built from focused subcomponents, exposed in case you want to
work at a lower level:

QRCodeGenerator::Config — version/error-level capacity, matrix size and alignment-pattern positions
QRCodeGenerator::Encoder — turns the input string into the encoded bit stream
QRCodeGenerator::ReedSolomon — error-correction codewords (with a GF256 Galois-field helper)
QRCodeGenerator::Matrix — the module grid with finder and alignment patterns

Logger & Error Messages

Logger

LUTS::Logger writes timestamped, levelled messages to both the console and a
log file (luts_log.txt). Each level has its own console colour.

LUTS::Logger.info("Plugin loaded")
LUTS::Logger.warn("Missing optional asset")
LUTS::Logger.error("Failed to read data file")
LUTS::Logger.debug("verbose detail")        # only when $DEBUG
LUTS::Logger.critical("Unrecoverable!")      # logs, then raises

LUTS::Logger.info(msg, options = {}) INFO level (console colour: cyan)
LUTS::Logger.warn(msg, options = {}) WARN level (brown)
LUTS::Logger.error(msg, options = {}) ERROR level (red)
LUTS::Logger.debug(msg, options = {}) DEBUG level — only emits when $DEBUG is truthy
LUTS::Logger.critical(msg, options = {}) logs at ERROR level and raises LUTS::ScriptError to halt the game
LUTS::Logger.log_msg(msg, options = {}) the underlying logger that all levels call (writes timestamp + level to console and file)

The options hash controls formatting (colour, headers, indentation, and
:skip_console to suppress console output). Helpers: timestamp,
console_color(type), log_path.

Error Messages

LUTS::ErrorMessages defines a family of ready-made error classes. Each builds
a descriptive message and reports it at an appropriate log level when you call
raise on the instance (routing through LUTS::Logger).

ImageNotFound.new(path) — a bitmap could not be found (level: error)
SpriteError.new(name) — no such Sprites::* class to instantiate (level: warn)
ComponentError.new(name) — a component could not be loaded (level: warn)
MissingFunctionError.new(klass, function) — an undefined method was called (level: warn)
VertexError.new(vertices = 3) — too few polygon vertices (level: error)

LUTS::ErrorMessages::ImageNotFound.new("Graphics/Pictures/foo").raise

All of these derive from BaseError; LUTS::ScriptError is the
StandardError subclass that Logger.critical raises to crash the game.

Math Helpers

LUTS::Math adds geometry helpers on top of Ruby's Math module — handy for
laying out shapes and scattering points.

LUTS::Math.polygon_points(n, radius:, width:, height:, angle: 0) the [x, y] coordinates of all n vertices of a regular polygon centred in a width × height area, rotated by angle degrees. Returns one pair per vertex.
LUTS::Math.rand_circle_coord(radius, x:) a random [x, y] point on the circumference of a circle of the given radius. Pass x: nil to also randomise the x-coordinate within the diameter.

# vertices of a hexagon inside a 128x128 box
points = LUTS::Math.polygon_points(6, radius: 60, width: 128, height: 128)
points.each { |x, y| bmp.set_pixel(x, y, Color.white) }

These pair naturally with Bitmaps::Polygon for drawing custom shapes (see
Bitmap Drawing).

UI Window (9-slice)

LUTS::UI::Window is a Sprites::Base subclass that renders a windowskin to a
bitmap using 9-slice scaling — the corners stay fixed while the edges and
centre stretch to fill the requested size. This lets one small skin graphic
produce a crisp window box at any dimension.

window = LUTS::UI::Window.new(viewport)
window.set_bitmap(
  width:  240,
  height: 120,
  path:   "Graphics/Windowskins/box",
  slice:  16
)

window.set_bitmap(width:, height:, path:, slice:) build the windowskin bitmap at width × height from the source image at path, using slice as the corner/edge boundary that defines the stretchable centre region

Because it inherits Sprites::Base, you also get all of its positioning,
colour and animation helpers on the resulting window sprite.

PBS Compiler

LUTS::Compiler is a schema-driven compiler that turns PBS text files into
serialized .dat game data at load time — the same pattern Essentials uses for
its own data, but reusable for a plugin's custom PBS. It only runs in debug
mode (when there is no packaged Game.rgssad archive), and it recompiles
incrementally.

LUTS::Compiler.compile(
  path:     "PBS/my_data",
  schema:   MyData,
  file_ext: "myextension"
)

API

LUTS::Compiler.compile(path:, schema:, file_ext:, force: false) compile every PBS .txt file in path against schema into serialized data files. force: true forces a full recompile.
LUTS::Compiler.compile_files(path) the unique base filenames in a PBS directory (collapsing name.txt and name_packN.txt into a single entry)
LUTS::Compiler.compile_data(path, schema:, const:) compile a single PBS file against a schema constant and return the parsed hash

When it recompiles

Compilation is skipped entirely unless $DEBUG is on and the path exists, and
no game archive is present. Within that, it recompiles when:

the compiled data file does not yet exist, or
you hold Input::CTRL during load (or pass force: true), or
any PBS source file is newer than the compiled data file.

PBS format it understands

Section headers: [TYPE], [TYPE, NAME], or [TYPE, NAME, VERSION] (CSV-parsed)
Properties: KEY = value, type-cast through the schema
Subsections: an all-caps SUBSECTION_NAME block terminated by END
Coordinate shorthand: a property ending in XY / XYZ expands into separate _x, _y, _z entries
"Pack" files (name_packN.txt) merge into their base file

The schema is a module/class carrying a LABEL constant (for log output) and a
nested ClassMethods::SCHEMA describing each property as [type, …] (or
:any for free parsing). POKEMON and TRAINERS ids are auto-filled when
omitted. Progress and failures are reported through LUTS::Logger.

Plugin Manager Helpers

LUTS extends Essentials' PluginManager and Console modules and ships a
mixin for safely composing plugins.

PluginManager

PluginManager.find_dir(plugin) returns the directory of an installed plugin by matching its name against the meta.txt files in the Plugins folder (or nil if not found)

dir = PluginManager.find_dir("Luka's Scripting Utilities")

Console echo helpers

Markup-aware echo helpers added to the Console module:

Console.echo_str(msg, options = {}) echo without a line break, applying markup / styling
Console.echo_p(msg, options = {}) echo with a line break (paragraph)

These pair with the String colour tags ("text".red, .green, …) from the
core extensions.

Aliaser

PluginManager::Aliaser is a mixin that bulk-aliases overlapping methods when
you prepend a module — letting a plugin override base methods while keeping the
originals callable. Include it in a class, then:

alias_with_module(alias_module, extension = 'old') prepend alias_module and auto-alias every overlapping instance, private and class method. Each original method is preserved under {name}_{extension} (e.g. update → update_old).
map_methods_for_alias(alias_module) the instance/private methods present in both the base class and the module
map_class_methods_for_alias(alias_module) the class methods present in both

class MyScene
  extend PluginManager::Aliaser
  alias_with_module(MyScenePatch, 'legacy')
  # MyScene#update is preserved as #update_legacy; MyScenePatch#update takes over
end

Class methods are matched against the module's nested ClassMethods, and an
existing alias is never overwritten. This is the mechanism that lets multiple
LUTS-based plugins layer behaviour on the same class without clobbering one
another.

Overview

How the documentation is organised

Ruby Object Extensions

Array

Hash

String

Constants & casing

Console colour tags

Numeric

Symbol & NilClass

Graphics Object Extensions

Color

Tone

Rect

Sprite

Viewport

Tagging

Sprites & compositing

Geometry & colour

Graphics

Filesystem & Environment

File

Dir

Env

Known path keys (COMMON_PATHS)

Animatable

How it works

API

QuickAnimatable

Floatable & Shaderable

Floatable

FloatValues

Shaderable

The Shader class

BlockConstructor

Helper Classes

AttributeContainer

CallbackWrapper

Sprites::Base

Extra attributes

Dimensions

Bitmaps

Colour effects

Positioning

Special Sprites

Sprites::Scrolling

Sprites::Rainbow

Sprites::Sheet

AnimatedPlane

SpriteHash

Adding sprites

Access & iteration

Bulk operations

Bitmap helpers

Bitmap Drawing

Text

Shapes

Colour & masking

Polygon rendering

Mouse Input

Cursor state

Buttons

Wheel

Hit testing

Dragging

Object extensions

Barcode Generator

Usage

Errors

QR Code Generator

Usage

Choosing a version

Supported range

Internals

Logger & Error Messages

Logger

Error Messages

Math Helpers

UI Window (9-slice)

PBS Compiler

Known path keys (`COMMON_PATHS`)