🧩 Understanding Components and Their Children in Limn Engine
A Complete Guide to Tile, Text, Sprite, AnimatedSprite, and Tctxt
📖 Introduction
The Component class is the foundation of every Limn Engine game. Everything you see on screen — players, enemies, coins, walls, text, sprites — is a Component or a child of Component.
But Component isn't just one thing. It has several specialized children that handle specific tasks:
| Child Class | Purpose |
|---|---|
| Tile | Individual tiles in a tilemap |
| Tctxt | Styled text with backgrounds |
| Sprite | Animated sprites from sprite sheets |
| AnimatedSprite | Multiple animation states |
| Particle | Individual particles (used internally) |
In this guide, we'll cover all of them — what they are, when to use them, and how they work.
🎯 What We'll Cover
- What is a Component?
- The Tile class — building blocks of levels
- The Tctxt class — styled text
- The Sprite class — animated characters
- The AnimatedSprite class — multiple animations
- The Particle class — visual effects
- Comparison table
- Common mistakes
🧩 Part 1: What Is a Component?
A Component is the most basic building block in Limn Engine. Every visible object in your game is a Component.
The Basics
// A basic Component
const player = new Component(40, 40, "#5b8cff", 400, 300, "rect");
display.add(player);
What this does:
-
new Component(40, 40, "#5b8cff", 400, 300, "rect")— Creates a 40x40 blue rectangle at position (400, 300). -
display.add(player);— Adds it to the game world.
Component Properties
| Property | Type | Purpose |
|---|---|---|
x, y |
number | Position |
width, height |
number | Size |
color |
string | Fill color |
speedX, speedY |
number | Velocity |
angle |
number | Rotation |
physics |
boolean | Enable gravity |
gravity |
number | Gravity strength |
Component Methods
| Method | Purpose |
|---|---|
move() |
Move based on speedX/speedY |
crashWith() |
Collision detection |
clicked() |
Mouse click detection |
setImage() |
Load an image |
setColor() |
Change color |
destroy() |
Remove from engine |
🧩 Part 2: The Tile Class — Building Blocks of Levels
Tile is a specialized Component used in tilemaps. Each tile represents a single cell in your level grid.
How Tiles Work
// Define a tile
const wallTile = new Component(64, 64, "#654321", 0, 0, "rect");
// In a tilemap, tiles are created automatically
display.tile = [
new Component(64, 64, "#1a3a1a", 0, 0), // 1 = grass
new Component(64, 64, "#2244aa", 0, 0), // 2 = water
new Component(64, 64, "#555555", 0, 0), // 3 = stone
];
display.map = [
[1,1,1,2,2,1,1,3,3,1],
[1,0,0,0,0,0,0,0,0,1],
[1,0,2,0,0,0,0,2,0,1],
];
display.tileMap();
display.tileFace.show();
What this does:
-
display.tile— An array of tile templates. -
display.map— A 2D array where each number refers to a tile template. -
display.tileMap();— Creates the tilemap object. -
display.tileFace.show();— Renders all tiles to the fake canvas.
Tile vs Component
| Aspect | Component | Tile |
|---|---|---|
| Purpose | General game objects | Individual tiles in a tilemap |
| Creation | Manual | Automatic from a map |
| Position | Set manually | Calculated from grid position |
| Use case | Players, enemies, items | Walls, floors, decorations |
🧩 Part 3: The Tctxt Class — Styled Text
Tctxt is a specialized Component for displaying styled text with backgrounds and padding.
The Basics
const scoreText = new Tctxt("24px", "Arial", "white", 20, 50);
scoreText.setText("Score: 0");
display.add(scoreText);
What this does:
-
new Tctxt("24px", "Arial", "white", 20, 50)— Creates text at (20, 50) with 24px Arial white text. -
scoreText.setText("Score: 0");— Sets the text content. -
display.add(scoreText);— Adds it to the game.
Full Constructor
const label = new Tctxt(
"20px", // size
"Arial", // font family
"white", // color
100, 200, // x, y
"center", // align: "left", "center", "right"
false, // stroke: false = fill, true = outline
"alphabetic", // baseline: "top", "middle", "bottom"
"rgba(0,0,0,0.5)", // background color (null = none)
10, 5 // paddingX, paddingY
);
Tctxt vs Component Text
| Aspect | Component (text) | Tctxt |
|---|---|---|
| Background | ❌ None | ✅ Yes |
| Padding | ❌ None | ✅ Yes |
| Alignment | ⚠️ Limited | ✅ Full |
| Stroke | ❌ None | ✅ Yes |
| Baseline | ❌ None | ✅ Yes |
| Ease of use | ⚠️ Basic | ✅ Advanced |
🧩 Part 4: The Sprite Class — Animated Characters
Sprite extends Component to handle animated sprite sheets.
The Basics
const hero = new Sprite("hero.png", 64, 64, 4, 10, 400, 300);
display.add(hero);
What this does:
-
new Sprite("hero.png", 64, 64, 4, 10, 400, 300)— Creates a sprite at (400, 300) from a sprite sheet with 4 frames, each 64x64, at speed 10.
How a Sprite Works
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Sprite Sheet: "hero.png" │
│ ┌──────────┬──────────┬──────────┬──────────┐ │
│ │ Frame 0 │ Frame 1 │ Frame 2 │ Frame 3 │ │
│ │ 64x64 │ 64x64 │ 64x64 │ 64x64 │ │
│ └──────────┴──────────┴──────────┴──────────┘ │
│ │
│ Sprite draws each frame in sequence: │
│ Frame 0 → Frame 1 → Frame 2 → Frame 3 → Frame 0... │
│ │
└─────────────────────────────────────────────────────────────────┘
Sprite Methods
| Method | Purpose |
|---|---|
update() |
Advance to the next frame |
draw(ctx, x, y) |
Draw the current frame |
play() |
Start/continue animation |
stop() |
Pause animation |
reset() |
Reset to frame 0 |
Sprite vs Component
| Aspect | Component | Sprite |
|---|---|---|
| Display | A single color/image | Multiple frames from a sprite sheet |
| Animation | ❌ None | ✅ Yes |
| Frame control | ❌ None | ✅ Full control |
| Use case | Simple objects | Characters, animated objects |
🧩 Part 5: The AnimatedSprite Class — Multiple Animations
AnimatedSprite extends Sprite to support multiple animation states.
The Basics
const hero = new AnimatedSprite("hero.png", 64, 64, 400, 300);
// Define animations
hero.addAnimation("idle", 0, 3, 10, true); // frames 0-3, loops
hero.addAnimation("run", 4, 11, 5, true); // frames 4-11, loops
hero.addAnimation("jump", 12, 15, 4, false); // frames 12-15, one-shot
hero.addAnimation("attack",16, 19, 3, false); // frames 16-19, one-shot
display.add(hero);
function update() {
if (isMoving) {
hero.playAnimation("run");
} else {
hero.playAnimation("idle");
}
hero.updateAnimation();
}
How Animations Work
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Sprite Sheet with multiple animations: │
│ │
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
│ │ Idle 0 │ Idle 1 │ Idle 2 │ Idle 3 │ Run 0 │ │
│ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │
│ │ Run 1 │ Run 2 │ Run 3 │ Run 4 │ Run 5 │ │
│ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │
│ │ Run 6 │ Jump 0 │ Jump 1 │ Jump 2 │ Jump 3 │ │
│ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │
│ │ Attack 0 │ Attack 1 │ Attack 2 │ Attack 3 │ │ │
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
│ │
│ Animations: │
│ - idle: frames 0-3 (loops) │
│ - run: frames 4-10 (loops) │
│ - jump: frames 12-15 (one-shot) │
│ - attack: frames 16-19 (one-shot) │
│ │
└─────────────────────────────────────────────────────────────────┘
AnimatedSprite Methods
| Method | Purpose |
|---|---|
addAnimation(name, start, end, speed, loop) |
Define an animation clip |
playAnimation(name) |
Switch to a different animation |
updateAnimation() |
Advance the frame counter |
faceLeft() |
Flip the sprite horizontally |
faceRight() |
Reset the flip |
The playAnimation Guard
playAnimation(name) {
// ⚡ CRITICAL GUARD: Prevents resetting if already playing
if (this.currentAnim === name) return;
// Only reset if the animation name changed
this.currentAnim = name;
this.currentFrame = anim.start;
this.frameSpeed = anim.speed;
this.loop = anim.loop;
}
Sprite vs AnimatedSprite
| Aspect | Sprite | AnimatedSprite |
|---|---|---|
| Animations | One continuous animation | Multiple named clips |
| State management | ❌ None | ✅ Built-in |
| Switching | ❌ Manual | ✅ playAnimation()
|
| Use case | Simple animations | Characters with multiple states |
🧩 Part 6: The Particle Class — Visual Effects
Particle is a specialized Component used in the ParticleSystem.
How Particles Work
// Particles are created by the ParticleSystem
const ps = new ParticleSystem(display);
// Single particle
ps.emit(x, y, {
color: "#ff6600",
life: 30,
gravity: 0.2
});
// Multiple particles
ps.burst(x, y, 20, {
color: "#ff6600",
life: 30,
randomSpeed: 5
});
What this does:
-
ps.emit()— Creates a single particle with custom options. -
ps.burst()— Creates multiple particles at once.
Particle Properties
| Property | Purpose |
|---|---|
life |
Frames until death |
gravity |
Downward acceleration |
friction |
Speed multiplier per frame |
alpha |
Starting opacity |
alphaFade |
Fade-out rate |
scale |
Starting size |
scaleFade |
Shrink rate |
📊 Comparison Table
| Class | Parent | Purpose | Use Case |
|---|---|---|---|
| Component | — | Base class for all objects | Players, enemies, items |
| Tile | Component | Individual tiles in a tilemap | Walls, floors, decorations |
| Tctxt | Component | Styled text with backgrounds | Score, menus, labels |
| Sprite | Component | Animated sprites from sprite sheets | Characters, animated objects |
| AnimatedSprite | Sprite | Multiple animation states | Characters with idle/run/jump |
| Particle | Component | Visual effects | Explosions, sparkles, blood |
⚠️ Common Mistakes
| Mistake | Why It's Wrong | How to Fix |
|---|---|---|
| Using Component for text | No background or alignment | Use Tctxt instead |
| Using Sprite for static images | Overkill for one frame | Use Component with setImage()
|
Not calling updateAnimation() |
Sprite doesn't animate | Call it every frame |
Forgetting the playAnimation guard |
Animation resets every frame | It's built-in, don't override it |
🎯 The One-Line Summary
"Component is the foundation — Tile builds levels, Tctxt displays text, Sprite animates characters, and AnimatedSprite manages multiple states."
Draw your game into existence — one component at a time. 🧩🚀
🔗 Resources
| Resource | Link |
|---|---|
| Limn Engine Docs | limn-engine-doc.vercel.app |
| API Reference | limn-engine-doc.vercel.app/reference.html |
| Beginner Guide | limn-engine-doc.vercel.app/beginner.html |
Top comments (0)