Crate tuig_iosys

source ·
Expand description

This crate was designed and built with tuig in mind. If you’re using tuig, see its docs, too, for how it uses this crate.

That said, tuig-iosys tries to be somewhat more broadly useful. It’s still hyperfocused on textmode outputs, but it doesn’t have all the extra “game engine” stuff. If you want to use it yourself, there are two central parts to familiarize yourself with.

The first is Screen. It’s a grid of formatted characters you can freely draw to. (If you’d like a UI system designed for chargrids that renders straight to it, consider tuig-ui!)

The second is IoSystem. You can use load! to pick one based on available features and which one succeeds first, or you can load them yourself. The IoSystem can be passed around wherever you like, but its associated IoRunner must be run on the main thread, to ensure things work as expected on Windows GUIs. Builtin backends are enabled by features and available in backends.

Features

There’s one feature to enable each builtin backend; see each backend for details. (When you see “available on has_backend only” in these docs, it refers to enabling at least one builtin.)

The std feature, on by default, enables std. Some backends aren’t available without it; you can still turn on their features but it’ll yell at you. All of fmt is no_std compatible.

There are also features controlling what extensions to fmt are available. This doesn’t influence the selection of backends, but backends will cheerfully ignore anything they don’t understand. See that module for details.

Custom backends

If you want to implement your own tuig-iosys compatible renderer, you’ll need an implementation of each of those traits. IoSystem is the Send/Sync handle with which to do the IO, and IoRunner occupies the main thread in case you need that, e.g. for GUI targets.

If you’re making a GUI backend, though, consider implementing im::GuiRenderer and using im::GuiSystem and im::GuiRunner – it uses winit to generate a graphical context and will ensure your GUI system handles input in the exact same way as every other.

Modules

  • backends
    Available rendering backends. See the IoSystem and IoRunner docs for more information.
  • fmt
    Implements CLI-compatible text formatting.
  • im
    Helper types for implementing your own (primarily graphical) IO systems.

Macros

  • cell
    Create a formatted Cell.
  • load
    Based on IO system features enabled, attempt to initialize an IO system; in order:
  • text
    Create a series of formatted Texts.
  • text1
    Create a single Text. Not recommended to be used directly.

Structs

  • Screen
    A text framebuffer.
  • XY
    A position or size, with an X and a Y component.

Enums

  • Action
    An action the player has taken in the IoSystem.
  • Error
    An error happened while trying to run an IO system.
  • Key
    A key which can be pressed or released in an Action.
  • MouseButton
    A mouse button which can be pressed or released in an Action.

Traits

Functions

  • load
    Based on IO system features enabled, attempt to initialize an IO system, in the same manner as load!.

Type Aliases