Loogine

A flexible OOP engine for Lua built on Luoop.

About

Loogine provides foundational classes and utilities for building complex Lua applications. It extends Luoop's OOP system with ready-to-use base classes, collections, and testing tools.

Built on Luoop: Loogine uses Luoop for class definitions, inheritance, and object lifecycle management.

Features

• Base classes — Object, NamedObject, Array, String
• Collection utilities — Advanced array with search, filter, and weighted random selection
• Value tracking — Objects track current and previous values
• Sprite support — Built-in image/sheet frame properties for game development
• Testing framework — Assertion functions for unit testing
• Helper utilities — Table manipulation, string formatting, math clamping

Installation

1. Clone or copy the repository to your project
2. Ensure Luoop is in the luoop/ directory

require("core.object")
require("core.array")
-- etc.

Core Classes

Object

Base class for all objects. Provides ID generation, value storage, and sprite support.

require("core.object")

-- Create an object with a value
local obj = Object("hello")

print(obj:getId())        -- 1 (auto-incremented)
print(obj:getValue())     -- "hello"

-- Update value (previous value is tracked)
obj:setValue("world")
print(obj:getValue())         -- "world"
print(obj:getPreviousValue()) -- "hello"

-- Sprite support for games
local sprite = Object(nil, "player.png")
print(sprite:getImageFile()) -- "player.png"

-- Or with sprite sheets
local animated = Object(nil, nil, spriteSheet, 3)
local sheet, frame = animated:toImage()

-- Clone an object
local clone = obj:clone()

-- Clean up
obj:destroy()

NamedObject

Extends Object with a name property.

require("core.namedObject")

local player = NamedObject(100, "Player One")

print(player:getName())   -- "Player One"
print(player:getValue())  -- 100

player:setName("Player Two")
print(player:getName())   -- "Player Two"

player:destroy()

Array

Advanced collection class with searching, filtering, and weighted random selection.

require("core.array")

local items = Array()

-- Basic operations
items:insert("sword")
items:insert("shield")
items:insert("potion")

print(items:size())           -- 3
print(items:getIndex(1))      -- "sword"
print(items:getFirstValue())  -- "sword"
print(items:getLastValue())   -- "potion"

-- Insert at specific index
items:insertAt(2, "armor")

-- Find and remove
local index = items:find("shield")
items:remove("shield")

-- Check existence
if items:exists(1) then
    print(items:get(1))
end

-- Random selection
local randomItem = items:drawRandomValue()

-- Destroy all
items:destroy(true)  -- true = also destroy contained objects

Array: Searching & Filtering

require("core.array")
require("core.namedObject")

local enemies = Array()
enemies:insert(NamedObject(100, "Goblin"))
enemies:insert(NamedObject(50, "Rat"))
enemies:insert(NamedObject(100, "Orc"))

-- Find by method result
local strongEnemies = enemies:getMatchingMethods("getValue", 100)
print(strongEnemies:size())  -- 2 (Goblin and Orc)

-- Find single element by name
local goblin = enemies:getMatchingElementByName("Goblin")

-- Find by ID
local enemy = enemies:getMatchingElementById(1)

-- Find by type
local orcs = enemies:getMatchingElementByType("NamedObject")

-- Run method on all elements
enemies:runMethod("setValue", 200)  -- Set all enemies to 200 HP

-- Get all names as table
local names = enemies:getValuesByName()  -- {"Goblin", "Rat", "Orc"}

enemies:destroy(true)

Array: Weighted Random Selection

require("core.array")

-- Create loot table with weighted probabilities
local loot = Array()
loot:insert({name = "Gold", getDropChance = function() return 50 end})
loot:insert({name = "Sword", getDropChance = function() return 30 end})
loot:insert({name = "Diamond", getDropChance = function() return 5 end})

-- Draw based on getDropChance method (higher = more likely)
local drop = loot:drawRandomWeightedValue("getDropChance")
print(drop.name)

-- Or set weights manually
loot:setRandomWeight(1, 1, 50)   -- Index 1: range 1-50
loot:setRandomWeight(2, 51, 80)  -- Index 2: range 51-80
loot:setRandomWeight(3, 81, 85)  -- Index 3: range 81-85

local manualDrop = loot:drawRandomPresetWeightedValue(1, 85)

String

String wrapper class extending Object.

require("core.string")

local greeting = String("Hello, World!")

print(greeting:getValue())   -- "Hello, World!"
print(greeting:toString())   -- "Hello, World!"
print(greeting:type())       -- "String"

greeting:setValue("Goodbye!")
print(greeting:getValue())   -- "Goodbye!"

greeting:destroy()

Helper Utilities

The tools.lua module provides standalone helper functions:

require("core.tools")

-- Math
local clamped = math.clamp(150, 0, 100)  -- 100

-- Strings
local parts = split("a,b,c", ",")  -- {"a", "b", "c"}
printf("Score: %d", 100)           -- "Score: 100"

-- Tables
local t = {a = 1, b = 2, c = 3}
print(getTableSize(t))             -- 3
print(getTableFirstElement(t))     -- 1

printTable(t)                      -- Prints all key-value pairs
local copy = copyTable(t)          -- Deep copy
clearTable(t)                      -- Remove all elements

Testing Framework

Loogine includes assertion functions for unit testing:

require("testing.test")

-- Nil checks
assert_nil(nil)
assert_not_nil("value")

-- Boolean checks
assert_true(1 == 1)
assert_false(1 == 2)

-- Equality
assert_equals(5, 5)
assert_not_equals(5, 10)

-- Comparisons
assert_less_than(5, 10)
assert_less_equal_than(5, 5)
assert_higher_than(10, 5)
assert_higher_equal_than(10, 10)

-- Tables and functions
assert_table_equals(t1, t1)
assert_table_not_equals(t1, t2)
assert_function_equals(fn, fn)

-- Method checks
assert_has_method(obj, "getValue")
assert_not_has_method(obj, "nonExistent")

Project Structure

Loogine/
├── luoop/              # Luoop OOP library (dependency)
│   └── luoop.lua
├── core/               # Core classes and utilities
│   ├── object.lua      # Base Object class
│   ├── namedObject.lua # NamedObject (extends Object)
│   ├── array.lua       # Array collection class
│   ├── string.lua      # String wrapper class
│   └── tools.lua       # Helper functions
├── testing/            # Testing framework
│   └── test.lua        # Assertion functions
└── LICENSE

Related Projects

• Luoop — The OOP library Loogine is built on

License

MIT License — see LICENSE for details.