Flint

A high-performance graphics engine for CC:Tweaked, written in Lua.

Flint lets you draw with arbitrary 24-bit hex colors instead of CC's 16 hardwired palette slots, composites multiple layers with z-ordering, and renders at up to 2× the horizontal and 3× the vertical resolution of a standard terminal using teletext mosaic characters. An optional CraftOS-PC pixel mode gives full per-pixel color fidelity with no two-color-per-cell limit.

---

Features

• Hex colors — use 0xff4444, 0x44aaff, or any 24-bit RGB value directly
• Auto palette quantization — when more than 16 colors appear in a frame, agglomerative clustering maps them to the 16 hardware slots with minimal visual loss
• Subpixel canvas — a virtual canvas of termWidth×2 × termHeight×3 subpixels, rendered as teletext mosaic characters for higher effective resolution
• Precomputed texel LUT — all 6⁶ subpixel color patterns are resolved at load time, so per-cell compositing is three table lookups
• Layer system — stack multiple drawing surfaces with z-index ordering and per-layer dirty rect tracking
• Diff-based present — only changed rows are sent to the terminal via blit(), minimizing CPU overhead
• CraftOS-PC pixel mode — opt-in mode where each subpixel maps to a real 3×3 pixel block; text is rasterized using the original CC bitmap font embedded in the engine

---

Installation

Copy flint.lua into your ComputerCraft computer and require it:

local flint = require("flint")

No external dependencies. Works in CC:Tweaked and CraftOS-PC. Pixel mode (setGraphicsMode) requires CraftOS-PC.

---

Quick Start

local flint = require("flint")

-- Create an engine bound to the current terminal
local sys = flint.new(term)

-- Add layers (lower zIndex = further back)
local bg = sys:addLayer(1)
local fg = sys:addLayer(2)

-- Optional: enable CraftOS-PC pixel mode (3×3 px per subpixel, full color)
sys:setGraphicsMode(true)

local vw, vh = sys.vWidth, sys.vHeight
local tw, th = sys.termWidth, sys.termHeight

-- Draw a title in the foreground layer
fg:drawText(2, 1, "Hello from Flint!", "0", "b")

-- Animate a sine wave in the background layer
local phase = 0
while true do
    bg:clear()

    for vx = 1, vw do
        local vy = math.floor(vh / 2 + math.sin(vx * 2 * math.pi / vw + phase) * (vh / 4) + 0.5)
        bg:drawSubpixel(vx, vy, 0x44aaff)
        bg:drawSubpixel(vx, math.max(1, vy - 1), 0x1a4f7a)
    end

    sys:compileSubpixels()
    sys:present()

    phase = phase + 0.1
    local timer = os.startTimer(0.05)
    while true do
        local ev, p1 = os.pullEvent()
        if ev == "timer" and p1 == timer then break end
        if ev == "char" and (p1 == "q" or p1 == "Q") then return end
    end
end

---

API Reference

flint.new(targetTerm) → Engine

Creates a new Flint engine attached to the given terminal. targetTerm must expose .blit() and .getSize() — term, window.create(...), and monitor objects all work.

---

Engine

sys:addLayer(zIndex) → Layer

Creates a new layer and registers it in draw order. Layers with a lower zIndex are drawn first (further back).

sys:clear()

Clears all registered layers.

sys:compileSubpixels()

Resolves the hardware palette, composites all layers into the output buffer, and marks changed rows for the next present() call. Call once per frame after all draw calls.

sys:present()

Flushes the composite buffer to the terminal using diff-based blit(). In pixel mode, renders real pixels via drawPixels(). Call after compileSubpixels().

sys:invalidate()

Forces a full repaint on the next present() call, clearing the blit cache. Useful after external terminal writes or palette resets.

sys:setGraphicsMode(enabled) → ok, reason?

Switches CraftOS-PC pixel graphics mode on (true) or off (false). Returns false, reason if the terminal does not support it (i.e. standard CC / Minecraft).

sys:setClipRegion(x, y, w, h)

Restricts all subsequent draw calls to the given cell rectangle. Both character-space and subpixel-space clip regions are updated.

sys:resetClipRegion()

Removes the clip region, restoring the full terminal extent.

---

Layer

Colors can be a CC palette slot ("0"–"f") or a 24-bit RGB integer (0xRRGGBB). nil means "leave unchanged" for optional parameters.

layer:clear(char?, fg?, bg?)

Clears all char, subpixel, and color data on this layer.

layer:clearVirtual(fg?, bg?)

Clears only the subpixel canvas, leaving character data intact. More efficient than clear() for subpixel-only layers.

layer:drawChar(x, y, char, fg?, bg?)

Writes a single character at terminal-cell position (x, y).

layer:drawText(x, y, text, fg?, bg?)

Writes a string starting at terminal-cell position (x, y).

layer:drawRect(x, y, w, h, char?, fg?, bg?)

Fills a rectangle in terminal-cell coordinates.

layer:drawSubpixel(vx, vy, color, bgColor?)

Sets a single subpixel on the virtual canvas at (vx, vy).

layer:drawSubpixelRect(vx, vy, vw, vh, color, bgColor?)

Fills a rectangle on the virtual canvas in subpixel coordinates.

layer:drawSubpixelLine(vx1, vy1, vx2, vy2, color)

Draws a Bresenham line on the virtual canvas between two subpixel positions.

---

Key properties (read-only after flint.new)

Property	Description
sys.termWidth / sys.termHeight	Terminal size in cells
sys.vWidth / sys.vHeight	Virtual canvas size in subpixels (termWidth×2 / termHeight×3)

---

License

MIT