Expand description
A macroquad window for an htl program.
htl new --target bin writes a host whose script runs to completion. A game wants the
other shape — a window, a frame loop, input, drawing — and the part of that which is
the same for every project is this crate; htl new --target window writes a project
on it. The project keeps its engine and its rules in Teal, and its own
#[host_module] beside mq for whatever wants the GPU.
Mq is a #[host_module] that re-exports macroquad’s drawing
and input to Teal as require("mq"). run drives a Teal game table (with
load, update(dt): boolean, and draw methods) through the frame loop; the
declaration names its shape mq.Game, each field ending in ---@noyield, because the
loop calls them with Function::call and a suspension inside one cannot reach an
executor.
Hooks provides the two environment hooks a run without a person at the window
needs. The declaration file dts/mq.d.tl is written by the #[host_module] macro
at build time and shipped through [package.metadata.htl] dts. macroquad is
re-exported, so a project that draws on its own side reaches it through this crate
rather than naming a version of its own — which is also why a window is a crate and
not a feature of htl: macroquad comes with it.
Not here: textures and audio, which need asset paths, and that is a host decision; and the web target, since macroquad’s wasm path and mlua’s are different targets.
§A window, end to end
[dependencies]
htl = "0.8"
htl-mq = "0.8" # macroquad comes with ituse htl::bundle::Bundle;
use htl::mlua::Table;
use htl::{Htl, include_bundle};
// `mq` is htl-mq's: its declaration is `types/htl-mq/mq.d.tl`, which `htl dts` writes.
// `host` is this crate's `#[host_module]`, which the build knows without being told.
const MAIN: &[u8] = include_bundle!("src/main.tl", host = ["game", "mq"], debug = true);
fn main() -> anyhow::Result<()> {
let h = Htl::new()?;
game::preload(&h)?; // the project's own host module and Teal
htl_mq::Mq.htl_preload(&h)?; // `require("mq")`
h.install_bundle(&Bundle::decode(MAIN)?)?;
let game: Table = h.lua().load("return require('main')").eval()?;
htl_mq::run(h, game, htl_mq::conf("game", 800, 600))
}The entry script returns the game table, bound to mq.Game so that htl check knows
what it is (under [lang] async, an async function given to update is reported by
async-as-sync-callback; { .. } as mq.Game is a cast the rule does not see through):
local mq = require("mq")
local x = 40.0
local game: mq.Game = {
update = function(dt: number): boolean
x = x + 120 * dt
return not mq:is_key_pressed("Escape")
end,
draw = function()
mq:clear_background({r = 0.08, g = 0.08, b = 0.12, a = 1})
mq:draw_circle(x, 300, 24, {r = 1, g = 0.6, b = 0.2, a = 1})
mq:draw_text("fps " .. mq:fps(), 16, 32, 28, {r = 1, g = 1, b = 1, a = 1})
end,
}
return gameRe-exports§
pub use macroquad;
Structs§
- Color
- Channels 0.0..=1.0, as macroquad’s.
- Hooks
- What a run without a person at the window needs: stop after
framesframes, and write the last frame drawn toshotas a PNG. Read fromHTL_MQ_FRAMESandHTL_MQ_SHOTbyHooks::from_env, whichrundoes;run_withtakes them explicitly, andHooks::NONEturns both off. A machine with no display fails before the first frame (XOpenDisplay() failed!on Linux);xvfb-runis enough to get the PNG out of one. - Mq
- Stateless, because macroquad keeps its state process-global; every method calls
macroquad and panics when no window is open, which is why a Teal test never calls
them —
htl testsees only the declaration, which declares and does nothing. So an engine module that takes what it needs as arguments is testable headless, andmain.tl— the one file that callsmq— is not what a test requires; that panic is the other reason to keep the loop out of the engine. - Vec2
- A 2D vector.
Enums§
- Key
- The subset of macroquad’s
KeyCodea game reaches for. On the Teal side it is anenum, so a string outside the set is anhtl checkerror that lists the variants, and one that reaches the host at run time is refused by name. - Mouse
Button
Functions§
- conf
- A window with a title and a size; everything else is macroquad’s default.
- run
- Open the window described by
confand drivegameuntilupdatereturns false, the window is closed, or theHTL_MQ_FRAMEShook is reached.his the state the table lives in; it is kept alive for the whole run. Hooks come from the environment;run_withis the same with them given. - run_
with runwith the hooks given rather than read from the environment.