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
- Implements CLI-compatible text formatting.
- Helper types for implementing your own (primarily graphical) IO systems.
Macros
- Create a formatted
Cell
. - Based on IO system features enabled, attempt to initialize an IO system; in order:
- Create a series of formatted
Text
s. - Create a single
Text
. Not recommended to be used directly.
Structs
- A text framebuffer.
- A position or size, with an X and a Y component.
Enums
- An action the player has taken in the
IoSystem
. - An error happened while trying to run an IO system.
- A key which can be pressed or released in an
Action
. - A mouse button which can be pressed or released in an
Action
.
Traits
- The other half of an
IoSystem
. - An input/output system.
Functions
- Based on IO system features enabled, attempt to initialize an IO system, in the same manner as
load!
.
Type Aliases
- Alias for
core::result::Result
with the error always beingError
.