# pixelParallax.ParallaxBackground
A parallax background behind a 2D scene: up to four layers (`sky`, `far`, `mid`, `near`), each a 320 x 180 picture on the `pixelParallax.parallax` shader scrolling at its own factor of the camera's motion, pixel-crisp. Put it on any scene entity; it follows `camera`, or the camera the renderer is using. Needs no sibling components. Fields and an example are in the package README.
# pixelParallax.parallax
Background bands for 2D parallax, any number of layers, driven by your own camera code. `create(layers, opts)` spawns one band per layer (`{ material, factor, yFactor?, stretch? }`, far first; `opts` = `baseY`, `depth`, `parent`, `name`), `update(p, { x, y, halfW, halfH, zoom? })` moves and rescrolls them for a view, `setVisible`, `destroy`. `bandUV(view, factor, yFactor, baseY, zoom)` is the pixel-exact mapping (scroll rounded to whole screen pixels). `IMAGE_W` / `IMAGE_H` = 20 x 11.25 world units per picture. Used by `pixelParallax.ParallaxBackground` and `twoDKit.parallax`.
# pixelParallax.parallax
Unlit, alpha-cut background band for 2D parallax. The quad rides with the camera and the image scrolls inside it, so each band appears at its own depth. Driven by the `twoDKit.parallax` module (which `twoDKit.Level2D` uses for each level's background); `Paint.material(folder, name, texture, "parallax")` writes a material on it.
Per-entity ShaderData lanes: `lane0 = (offsetU, offsetV, scaleU, scaleV)` maps the quad's uv onto the image (`uv * scale + offset`, wrapped horizontally); `lane1.x > 0.5` stretches the top and bottom rows past the image (for a sky band), otherwise the band is empty above and below the image. Give the texture `wrapU = repeat` and `filter = nearest`.
# pixelSprites: animated pixel-art sprites from any sprite sheet
Draw a character or object as a flat pixel-art picture that plays named animations from a sprite sheet, in any Zero world, with no other kit. It is the sprite layer of [twoDKit](https://origozero.ai) and works on its own.
- **`SpriteSheet` component**: name your animations once as rows of the sheet (`"idle=0:6:8, run=1:8:14, jump=2:3:12:once"`), then switch with one field (`anim`). It faces left or right (`facing`), stays snapped to the art's pixel grid so it never shimmers, and `anim` and `facing` sync, so every player sees every other player's animation.
- **`sprites` module**: attach a picture showing one cell of a sheet to any entity and drive it yourself: `setCell`, `setFlash` (hit flash), `setFade` (dithered fade), `setTint`, `setSquash` (squash and stretch that stays pixel-crisp), `snapTo`.
- **`sprite` shader**: unlit, alpha-cut, nearest-filtered; one material draws every sprite that uses the sheet.
## Install
```lua
tools.use("zeromind", "installAsset", "af866662-98d1-4500-bd67-49508538bb47") -- or `zero zeromind installAsset af866662-98d1-4500-bd67-49508538bb47` in the shell
```
or search ZeroMind for "pixelSprites" / "animated sprite sheet". It lands at `/source/pixelSprites.package`.
## Your first animated sprite
A sheet is a texture with the frames in a grid, top row first, and a material on the `pixelSprites.sprite` shader. Make the material by importing your sheet as a texture (nearest filter) and creating a material whose shader is `pixelSprites.sprite` with that texture as its base colour, or paint one in code with twoDKit's `twoDKit.paint` (`Paint.save` then `Paint.material`). With one in hand:
```lua
function content()
local hero = entity.spawn("Hero", { position = { 0, 1, 0 } }) -- the position is the feet
hero.component.add("pixelSprites.SpriteSheet", {
sheet = asset.resolve("my.art.hero", "material"),
frameWidth = 32, frameHeight = 32, columns = 8, rows = 8,
animations = "idle=0:6:8, run=1:8:14, jump=2:3:12:once, fall=3:3:10",
})
end
```
Then, from your own code: `hero.component.get("pixelSprites.SpriteSheet").anim = "run"` and `.facing = -1` to face left. `:play("jump", true)` restarts an animation, `:isFinished()` says whether a `:once` animation reached its last frame.
## SpriteSheet fields
| Field | Default | What |
|---|---|---|
| `sheet` | none | The material (on the `pixelSprites.sprite` shader). |
| `frameWidth`, `frameHeight` | `32` | One frame in pixels. |
| `columns`, `rows` | `8` | The sheet's grid. |
| `animations` | `idle=0:1:1` | `name=row:frames:fps`, add `:once` to hold the last frame; rows count from the top, starting at 0. |
| `anim` | `idle` | The animation playing (synced). |
| `facing` | `1` | `1` as drawn, `-1` mirrored (synced). |
| `speed` | `1` | Animation speed multiplier. |
| `pixelsPerUnit` | `16` | Art pixels per world unit. |
| `pixelSnap` | `true` | Keep the picture on the art's pixel grid. |
| `z` | `0` | Depth offset. |
## Notes
- The picture is drawn on a temporary child entity on each peer; nothing about it is saved or sent except `anim` and `facing`.
- For crisp pixels on screen use an orthographic camera whose height is the window height divided by a whole number of screen pixels per art pixel (twoDKit's `Camera2D` does this, and `pixelParallax` scrolls backgrounds to match).
- The engine's own flipbook (`animatedTexture`) plays texture layers on a clock; it cannot pick named animations or mirror, which is why this package exists.
## Changelog
- **1.1.0**: a SpriteSheet can take a plain sprite-sheet texture (`texture`) instead of a material; pixelSprites builds the sprite material from it at runtime (`Sprites.sheetMaterial`), so a game ships the texture alone, with no material asset or material preview per sheet. `sheet` works exactly as before.
- **1.0.3**: this changelog. No change to the component, module or shader.
- **1.0.2**: the package description says what it gives you and how to install it.
- **1.0.1**: real install lines in the README, and how to make a sheet material.
- **1.0.0**: first release, split out of twoDKit 1.1.0: the `SpriteSheet` component, the `sprites` module and the `sprite` shader.
# pixelSprites.SpriteSheet
An animated pixel-art sprite from any sprite sheet, on any entity. Name the animations as rows of the sheet (`animations = "idle=0:6:8, run=1:8:14, jump=2:3:12:once"`) and switch with `anim`; `facing = -1` mirrors it. The entity's position is the picture's bottom-centre (the feet). `anim` and `facing` sync, so every player sees the same animation; each peer draws the picture on a temporary child. Needs no sibling components; the `sheet` is a material on the `pixelSprites.sprite` shader.
Methods: `play(name, restart?)`, `isFinished()` (for `:once` animations). Fields and an example are in the package README.
# pixelSprites.sprite
Unlit, alpha-cut surface for pixel art: shows one cell of a sprite sheet, chosen per entity, so one material draws every sprite that shares a sheet. Level tilemaps use it too (with their atlas UVs baked into the mesh); parallax backgrounds use `twoDKit.parallax` instead.
Per-entity ShaderData lanes:
| Lane | x | y | z | w |
|---|---|---|---|---|
| `lane0` | column | row (from the top) | columns in the sheet | rows in the sheet |
| `lane1` | flipX (> 0.5 mirrors) | flash toward white 0..1 | dithered fade 0..1 | unused |
| `lane2` | tint r | tint g | tint b | tint amount 0..1 |
| `lane3` | drawn width (art px) | drawn height (art px) | quad width (art px) | quad height (art px) |
`lane3` is the pixel-crisp squash and stretch: on a padded quad pivoted at its bottom-centre, the frame is drawn `x` by `y` art pixels (each art pixel shows one texel, rows and columns repeat or drop, nothing blurs). Zero leaves the quad drawing the frame 1:1. `twoDKit.sprites` sets it with `Sprites.setSquash`.
Lanes left at zero draw the whole texture untinted, which is what a tilemap mesh with baked atlas UVs wants. Pair it with a texture whose `filter` is `nearest` for crisp pixels; `twoDKit.paint`'s `Paint.material(folder, name, textureIdentity)` writes such a material for any sheet, and `twoDKit.sprites` drives the lanes.
Properties: `base_color` (multiplier), `alpha_cutoff` (default 0.5), `base_color_texture` (the sheet).
# sprites
Draws a flat pixel-art picture showing one cell of a sprite sheet on any entity, without a component: pick the cell, mirror it, flash it white, dither-fade it, tint it, and keep it snapped to the art's pixel grid so it never shimmers. It is the shared drawing code behind `twoDKit.Sprite2D`, the level's gems, flags and moving-platform planks, and the kit's effects.
`attach` spawns a temporary child entity under the host (so every peer draws its own and nothing is saved) holding a quad pivoted at the bottom-centre of the frame, one world unit per 16 art pixels (`Sprites.PPU`). The material must use the kit's `twoDKit.sprite` shader; the cell, flip, flash, fade and tint are written to the child's per-entity shader data lanes, so one material serves every sprite on the same sheet.
## API
- `Sprites.attach(hostId, opts) -> View`: opts: `material` (required), `frameWidth`, `frameHeight` (pixels, default 16), `columns`, `rows` (default 1), `z` (depth offset), `snap` (default true), `pivotX`, `pivotY` (0..1, default 0.5, 0), `name`, `scale`.
- `Sprites.setCell(view, col, row, flip?)`: show cell (col, row) counted from the top-left; `flip` mirrors horizontally.
- `Sprites.setFlash(view, 0..1)`: mix toward white (hit flash).
- `Sprites.setFade(view, 0..1)`: ordered-dither transparency (blink, ghost).
- `Sprites.setTint(view, r, g, b, amount)`: mix toward a colour.
- `Sprites.setVisible(view, bool)`: show or hide.
- `Sprites.setMaterial(view, material, opts?)`: swap the sheet; with `opts` also change frame size and grid (the quad is rebuilt).
- `Sprites.snapTo(view, worldX, worldY)`: offset the picture so it lands on the 1/16 pixel grid for a host at that position (no-op when `snap` is off).
- `Sprites.alive(view)`, `Sprites.detach(view)`.
- `Sprites.quad(w, h, pivotX?, pivotY?)`: the cached quad mesh used for sprites and parallax bands.
```luau
local Sprites = require("pixelSprites.sprites")
local mat = asset.resolve("twoDKit.art.fx.fx", "material")
local v = Sprites.attach(e.id, { material = mat, frameWidth = 16, frameHeight = 16, columns = 8, rows = 8 })
Sprites.setCell(v, 0, 5) -- first frame of the gem row
Sprites.snapTo(v, e.position.x, e.position.y)
Sprites.detach(v)
```
For an animated, network-synced sprite with named animations use `pixelSprites.SpriteSheet` (or twoDKit's `Sprite2D` for the kit's characters).