Skip to main content

Crate htl_mq

Crate htl_mq 

Source
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 it
ⓘ
use 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 game

Re-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 frames frames, and write the last frame drawn to shot as a PNG. Read from HTL_MQ_FRAMES and HTL_MQ_SHOT by Hooks::from_env, which run does; run_with takes them explicitly, and Hooks::NONE turns both off. A machine with no display fails before the first frame (XOpenDisplay() failed! on Linux); xvfb-run is 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 test sees only the declaration, which declares and does nothing. So an engine module that takes what it needs as arguments is testable headless, and main.tl — the one file that calls mq — 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 KeyCode a game reaches for. On the Teal side it is an enum, so a string outside the set is an htl check error that lists the variants, and one that reaches the host at run time is refused by name.
MouseButton

Functions§

conf
A window with a title and a size; everything else is macroquad’s default.
run
Open the window described by conf and drive game until update returns false, the window is closed, or the HTL_MQ_FRAMES hook is reached. h is the state the table lives in; it is kept alive for the whole run. Hooks come from the environment; run_with is the same with them given.
run_with
run with the hooks given rather than read from the environment.