lovemachine

A lightweight Entity Component System (ECS) framework for LÖVE (Love2D) written in Lua.

Lovemachine provides a clean, minimal ECS foundation designed for flexibility and rapid iteration. It separates data (components), identity (entities), and behavior (systems) while remaining small enough to fully understand and extend.

---

Features

• Clean Entity--Component--System architecture
• Modular and extensible design
• World management
• Level manager
• Built-in event system (pub/sub)
• Optional built-in rendering components
• Designed for LÖVE integration
• No external dependencies

---

Installation

Clone the repository into your project:

git clone git@github.com:nclarke-development-studio/lovemachine.git

Then require it in your project:

local LM = require("lovemachine")

Make sure your Lua path includes the directory containing lovemachine.

---

Example

local LM = require("lovemachine")

local world = LM.World.new("main")

-- Register systems
world:register(LM.Systems.rectangle_renderer())

-- Create an entity with components
world:assemble({
    { LM.Components.body, 400, 300 },
    { LM.Components.rectangle, 64, 64 }
})

function love.update(dt)
    world:update(dt)
end

function love.draw()
    world:draw()
end

---

Core Concepts

Entity

Entities are containers for components.

local entity = world:create()
entity:add(component)
entity:addTag("player")

Entities: - Hold components - Can be tagged - Can be safely destroyed - Are processed by systems

---

Component

Components are pure data.

local component = LM.Component.new("health")
component.value = 100

Components: - Have an ID - Store only data - Contain no behavior

---

System

Systems define behavior.

A system operates on entities that contain specific components.

local system = LM.System.new({"body", "rectangle"})

Systems can override:

• load(entity)
• update(dt, entity)
• updateOnce(dt)
• draw(entity)
• drawOnce()
• destroy(entity)
• unload()

---

World

The world manages:

• Entities
• Systems
• Update loop
• Draw loop
• Entity lifecycle

world:update(dt)
world:draw()

---

Event System

Simple pub/sub event system:

local events = world.EventSystem

events:Add("damage")

events:Register("damage", entity, function(self, amount)
    print("Took damage:", amount)
end)

events:FireEvent("damage", {10})

---

Project Structure

lovemachine/
│
├── core/
│   ├── component.lua
│   ├── entity.lua
│   ├── system.lua
│   ├── world.lua
│   ├── events.lua
│   └── level_manager.lua
│
├── common/
│   ├── common_components/
│   └── common_systems/
│
├── helpers/
│   └── Vector2D.lua
│
└── init.lua

Structure Overview

• core/ --- ECS engine logic
• common/ --- Built-in components and systems
• helpers/ --- Utility modules
• init.lua --- Public API entry point

---

Design Goals

Lovemachine aims to be:

• Simple
• Understandable
• Lightweight
• Flexible
• Unopinionated

It does not try to be a full game engine. It provides structure without forcing patterns.

---

Future Improvements

Potential enhancements:

• System execution ordering / priorities
• Improved event cleanup for destroyed entities
• Prefab system
• Serialization support
• Scene management improvements
• Engine-agnostic rendering layer

---

License

MIT License

---

Contributing

Pull requests and improvements are welcome.

If you build something using Lovemachine, feel free to share it!