Using Parallax
Project Structure
How Parallax organizes your Love2D game files.
Project Structure
A Parallax project is a standard Love2D project with a few extra conventions the agent understands.
Default layout
my-game/
main.lua # Entry point — love.load, love.update, love.draw
conf.lua # Love2D window and module config
player.lua # Player entity (auto-created for non-blank templates)
physics.lua # Physics helpers and collision groups
assets/
images/ # Sprites and backgrounds (.png)
audio/ # Sound effects and music (.ogg, .mp3)
fonts/ # Bitmap and TTF fonts
lib/ # Third-party Lua libraries (e.g. hump, bump.lua)
.parallax/
context.json # Agent context: genre, rules, decisions made
history.jsonl # Local cache of agent conversation
Key files the agent watches
| File | Purpose |
|---|---|
main.lua | Core game loop — the agent always has this in context |
conf.lua | Window size, enabled modules — agent reads this to understand your canvas |
.parallax/context.json | Your game's "constitution" — genre, player rules, world rules |
The context file
.parallax/context.json is the agent's long-term memory for your project. You can edit it directly:
{
"genre": "platformer",
"player": {
"speed": 200,
"jump_force": 400,
"has_double_jump": true
},
"world": {
"gravity": 600,
"tile_size": 16
},
"conventions": [
"All entities are tables with :update(dt) and :draw() methods",
"Collision uses bump.lua — never raw AABB"
]
}
The conventions array is especially powerful — add your own coding rules and the agent will follow them.
Adding libraries
Drop Lua libraries into lib/ and require them normally:
local bump = require('lib.bump')
local flux = require('lib.flux')
The agent knows common Love2D libraries by default: bump.lua, hump, flux, lume, sti, anim8.