<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>SGE Documentation</title>
<meta name="robots" content="noindex">
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon-de23e50b.svg">
<link rel="shortcut icon" href="favicon-8114d1fc.png">
<link rel="stylesheet" href="css/variables-8adf115d.css">
<link rel="stylesheet" href="css/general-2459343d.css">
<link rel="stylesheet" href="css/chrome-ae938929.css">
<link rel="stylesheet" href="css/print-9e4910d8.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="fonts/fonts-9644e21d.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
<link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
<link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "ayu";
window.path_to_searchindex_js = "searchindex-b6b2c3d7.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc-c49a7683.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="mdbook-body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="mdbook-page-wrapper" class="page-wrapper">
<div class="page">
<div id="mdbook-menu-bar-hover-placeholder"></div>
<div id="mdbook-menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
</label>
<button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
</button>
<ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
</ul>
<button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
</button>
</div>
<h1 class="menu-title">SGE Documentation</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
</a>
<a href="https://github.com/LilyRL/sge" title="Git repository" aria-label="Git repository">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span>
</a>
</div>
</div>
<div id="mdbook-search-wrapper" class="hidden">
<form id="mdbook-searchbar-outer" class="searchbar-outer">
<div class="search-wrapper">
<input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
</div>
</div>
</form>
<div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
<div id="mdbook-searchresults-header" class="searchresults-header"></div>
<ul id="mdbook-searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="mdbook-content" class="content">
<main>
<h1 id="simple-game-engine"><a class="header" href="#simple-game-engine">Simple Game Engine</a></h1>
<p>SGE requires that you have the Rust toolchain installed, and some familiarity
with rust.</p>
<p>To create a new Rust project, you can run <code>cargo new my_project</code>, and replace
my_project with whatever you want to call your game/app. To add SGE to your project run <code>cargo add sge</code>.</p>
<pre><code class="language-sh">cargo new my_project
cd my_project
cargo add sge
</code></pre>
<p>Throughout this guide there will be links to examples that you can read and use
to find out more about how SGE works and how to use it. To run these, clone the
repository and use <code>cargo run --example</code> like so:</p>
<pre><code class="language-sh">git clone https://github.com/lilyRL/sge
cd sge
cargo run --example name_of_example
</code></pre>
<p>Do not include the <code>.rs</code> in the name of the example.</p>
<h2 id="nix"><a class="header" href="#nix">Nix</a></h2>
<p>If you use Nix/NixOS, there is a <a href="https://github.com/LilyRL/sge/blob/master/shell.nix"><code>shell.nix</code></a> included in the repository that you
can use to build and use the engine, though it was written with Wayland in mind.
If you don’t know what Nix is you can safely ignore this entirely.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="architecture"><a class="header" href="#architecture">Architecture</a></h1>
<p>SGE was designed to be flexible and easy to use, even for someone
unfamiliar with Rust, for this reason it does not impose any set structure on
how you must organize your code.</p>
<p>The most basic SGE project is a single file with this structure:</p>
<pre class="playground"><code class="language-rust">use sge::*;
#[main("Title for the window")]
async fn main() {
// do initialization here
loop {
// if you don't include this, it will be cleared to black by default.
// if you don't want to clear the screen, use `dont_clear_screen()` instead
clear_screen(Color::BLACK)
// frame loop here
// do anything you want to run once per frame, like drawing some shapes
if should_quit() {
// you can do whatever you want here
// i just find it makes more sense to break out of the loop
// and do the cleanup at the bottom of the function
break;
}
next_frame().await;
}
// do cleanup here
}</code></pre>
<p>For more complex apps it may make more sense to store state in a struct, created
at the start of the main function, and then have a frame loop comprised of just <code>state.update()</code>.</p>
<p>The main function can optionally return a result (anyhow is included, use
<code>anyhow::Result<()></code>), which will be unwrapped.</p>
<p>Most functions that return a large amount of data (for example loading a
texture or sound) actually return a reference to the data, so you can pass around your
<code>TextureRef</code> (for example), and clone/copy it without worrying about the
performance cost.</p>
<p>We will talk more about why async is needed, what the <code>#[main]</code> macro is for,
and how to initialize the engine with custom parameters later.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="drawing-shapes"><a class="header" href="#drawing-shapes">Drawing Shapes</a></h1>
<p>There are two main spaces that shapes can be drawn to.</p>
<ol>
<li>Screen space: coordinates are relative to the top left of the screen, and one unit always corresponds to one pixel. Positive y is down, positive x is right.</li>
<li>World space: coordinates are relative to the position and scale of the <code>Camera2D</code>. Moving the camera changes what is shown on screen, and one world unit does not always correspond to one pixel. By default, world coordinate <code>(0, 0)</code> is in the center of the screen.</li>
</ol>
<p>Every shape drawing function comes in three variants:</p>
<ul>
<li><code>draw_<shape>(...)</code> — draws in screen space</li>
<li><code>draw_<shape>_world(...)</code> — draws in world space</li>
<li><code>draw_<shape>_to(..., renderer)</code> — draws to a specific renderer</li>
</ul>
<h2 id="shapes"><a class="header" href="#shapes">Shapes</a></h2>
<p>The following shapes are available:</p>
<ul>
<li>Circles and ellipses: <code>draw_circle</code>, <code>draw_ellipse</code>, <code>draw_circle_outline</code>, <code>draw_ellipse_outline</code>, <code>draw_circle_with_outline</code>, <code>draw_ellipse_with_outline</code></li>
<li>Sectors and arcs: <code>draw_sector</code>, <code>draw_sector_outline</code>, <code>draw_sector_with_outline</code>, and ellipse variants of each. Angles are in radians.</li>
<li>Rings: <code>draw_ring</code>, <code>draw_full_ring</code>, <code>draw_arc</code></li>
<li>Rectangles and squares: <code>draw_rect</code>, <code>draw_square</code>, with optional rotation and outline variants. Rounded corners are supported via <code>draw_rounded_rect</code> and <code>draw_rounded_square</code>.</li>
<li>Polygons: <code>draw_poly</code> for arbitrary n-sided regular polygons, <code>draw_hexagon</code>, <code>draw_hexagon_pointy</code> for flat and pointy-top hexagons.</li>
<li>Lines: <code>draw_line</code>, <code>draw_capped_line</code> (with rounded ends), <code>draw_dashed_line</code>, <code>draw_zig_zag</code>, <code>draw_rounded_line</code></li>
<li>Arrows: <code>draw_arrow</code>, <code>draw_solid_arrow</code>, <code>draw_sharp_arrow</code>, and right-angled variants of each</li>
<li>Paths: <code>draw_path</code> (connected line segments), <code>draw_connected_path</code> (with caps at each join), <code>draw_circle_path</code> (with circular dots at each point)</li>
<li>Curves: <code>draw_quadratic_bezier</code>, <code>draw_cubic_bezier</code></li>
<li>Triangles and quads: <code>draw_tri</code>, <code>draw_quad</code></li>
<li>Custom shapes: <code>draw_custom_shape</code> builds a mesh from an arbitrary slice of points</li>
<li>Niche shapes: <code>draw_pentagon</code>, <code>draw_octogon</code>, <code>draw_hexagram</code>, <code>draw_pentagram</code>, <code>draw_star</code>, <code>draw_moon</code>, <code>draw_heart</code>, <code>draw_quadratic_circle</code></li>
<li>Pixels: <code>draw_pixel</code>, <code>draw_pixel_line</code></li>
<li>Metaballs: <code>draw_metaballs</code></li>
<li>SDFs: <code>draw_sdf</code> for drawing an <code>Sdf</code> object directly (see <a href="#advanced-shapes">Advanced Shapes</a>)</li>
</ul>
<h2 id="outlines"><a class="header" href="#outlines">Outlines</a></h2>
<p>Most shapes have outline and with-outline variants:</p>
<ul>
<li><code>draw_<shape>_outline(...)</code> — draws just the outline, no fill</li>
<li><code>draw_<shape>_with_outline(...)</code> — draws the shape with both fill and outline</li>
</ul>
<p>For example, to draw a square in world space with an outline:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>draw_square_with_outline_world(
vec2(20.0, 30.0), // top_left
40.0, // size
Color::RED_500, // fill
2.0, // outline thickness
Color::RED_300, // outline color
);
<span class="boring">}</span></code></pre>
<h2 id="gradients"><a class="header" href="#gradients">Gradients</a></h2>
<p>Multipoint linear gradients can be drawn with <code>draw_multipoint_gradient</code>, which takes a list of <code>GradientPoint</code>s each with a color and relative width, and an <code>Orientation</code> (horizontal or vertical).</p>
<p>For radial gradients and more advanced fill effects, use the <code>Sdf</code> type directly (see <a href="#advanced-shapes">Advanced Shapes</a>).</p>
<hr>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/simple.rs"><code>/examples/simple.rs</code></a></p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/shapes/index.html">all shape drawing functions</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="color-type"><a class="header" href="#color-type">Color type</a></h1>
<p>SGE comes with a <code>Color</code> type, with rgba as <code>f32</code> values from 0.0 to 1.0.</p>
<h2 id="creating-colors"><a class="header" href="#creating-colors">Creating colors</a></h2>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// float (0.0–1.0)
Color::from_rgb(1.0, 0.5, 0.0)
Color::from_rgba(1.0, 0.5, 0.0, 0.8)
// u8 (0–255)
Color::from_rgb_u8(255, 128, 0)
Color::from_rgba_u8(255, 128, 0, 200)
// hsl
Color::from_hsl(30.0, 1.0, 0.5)
Color::from_hsla(30.0, 1.0, 0.5, 0.8)
// oklch
Color::from_oklch(0.7, 0.15, 142.0)
Color::from_oklch_with_alpha(0.7, 0.15, 142.0, 0.8)
// From hex constant (compile-time)
Color::hex(0xFF8800)
Color::hex_alpha(0xFF8800FF)
// from a string at runtime (rgb, hsl, oklch, hex, and named colors)
Color::from_string("oklch 0.7 0.15 142")
Color::from_string("#FF8800")
Color::from_string("rgb 1.0 0.5 0.0")
Color::from_string("rebecca purple")
// every CSS and Tailwind color is available as a constant
Color::RED_500
Color::NEUTRAL_900
Color::CYAN_400
<span class="boring">}</span></code></pre>
<h2 id="modifying-colors"><a class="header" href="#modifying-colors">Modifying colors</a></h2>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>color.with_alpha(0.5)
color.with_red(1.0)
color.with_alpha8(128) // u8
color.lighten(0.2)
color.darken(0.3)
// or oklch
color.lighten_oklch(0.2)
color.darken_oklch(0.1)
color.saturate(0.5)
color.desaturate(0.3)
color.hue_rotate(90.0) // degrees, HSL
color.hue_rotate_oklch(45.0) // degrees, oklch
color.inverted()
Color::blend_two(Color::RED_500, Color::BLUE_500, 0.5)
color.blend(other, 0.3)
color.blend_halfway(other)
Color::grey(0.5) // brightness
<span class="boring">}</span></code></pre>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/tailwind_colors.rs"><code>/examples/tailwind_colors.rs</code></a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/css_colors.rs"><code>/examples/css_colors.rs</code></a></p>
<h2 id="palettes"><a class="header" href="#palettes">Palettes</a></h2>
<p>Tailwind color palettes are availible from 50 to 950.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let shades = Color::RED.shades(); // light to dark
let shades = Color::BLUE.reversed_shades(); // dark to light
<span class="boring">}</span></code></pre>
<h2 id="converting-colors"><a class="header" href="#converting-colors">Converting colors</a></h2>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>color.to_oklch() // (lightness, chroma, hue)
color.to_hex_string() // "#RRGGBBAA"
color.to_hex() // u32
color.to_color_u8() // ColorU8 (for images)
color.to_linear() // sRGB to linear RGB
<span class="boring">}</span></code></pre>
<h2 id="color-schemes"><a class="header" href="#color-schemes">Color schemes</a></h2>
<p>There are some built in
<a href="https://docs.rs/sge/latest/sge/prelude/color/struct.ColorScheme.html#impl-ColorScheme-1">colorschemes</a>
you can use if you like.</p>
<hr>
<p>Check the <a href="https://docs.rs/sge/latest/sge/prelude/struct.Color.html">reference documentation</a> for the full list of methods.</p>
<p>See also: <a href="https://docs.rs/sge/latest/sge/prelude/color/index.html">color related documentation</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="input-api"><a class="header" href="#input-api">Input API</a></h1>
<p>The input API is simple, SGE provides functions for querying the current
state of keyboard and mouse buttons.</p>
<p>If you want to run some code whenever the space bar is pressed, you could use
this code inside of your frame loop:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>if key_pressed(KeyCode::Space) {
// do whatever
}
<span class="boring">}</span></code></pre>
<p>There are also functions for mouse buttons, and keys being held and released:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>key_held(KeyCode::KeyA);
mouse_released(MouseButton::Left);
<span class="boring">}</span></code></pre>
<p>You can also query the position of the cursor:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>pub fn cursor() -> Option<Vec2>; // current position of the cursor, if it is in the window
pub fn last_cursor_pos() -> Vec2; // if the mouse cursor is outside the window, return it's last position
pub fn cursor_diff() -> Vec2; // how much the cursor moved
<span class="boring">}</span></code></pre>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/input/index.html">input module documentation</a> for more detail.</p>
<h2 id="action-mapping"><a class="header" href="#action-mapping">Action mapping</a></h2>
<p>There is support for creating named actions, and binding them to keys/mouse
buttons. You can then use equivalent functions to check if they are pressed/released/held.</p>
<p>Actions are most easily created using the <code>actions!</code> macro.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>actions! {
FWD, BACK, RIGHT, LEFT, JUMP
}
// Generated code:
// const FWD: Action = Action::new(0);
// const BACK: Action = Action::new(1);
// const RIGHT: Action = Action::new(2);
// const LEFT: Action = Action::new(3);
// const JUMP: Action = Action::new(4);
<span class="boring">}</span></code></pre>
<p>You can then bind an action to a key by using the <code>bind</code> function.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>bind(FWD, KeyCode::KeyW);
bind(BACK, KeyCode::KeyS);
bind(RIGHT, KeyCode::KeyD);
bind(LEFT, KeyCode::KeyA);
bind(JUMP, KeyCode::Space);
<span class="boring">}</span></code></pre>
<p>And use them like any other button.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>if action_pressed(FWD) {
// move forward
}
<span class="boring">}</span></code></pre>
<p>This makes it easier for you to allow the player to change their preferred
controls for your game, by binding them to different keys, without you needing
to change the rest of your codebase.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/input/index.html">input module documentation</a> for more detail.</p>
<p>See also: <a href="https://github.com/LilyRL/sge/blob/master/examples/action_mapping.rs"><code>/examples/action_mapping.rs</code></a></p>
<p>See also: <a href="https://docs.rs/sge/latest/sge/prelude/clipboard/index.html">clipboard module documentation</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="gamepad"><a class="header" href="#gamepad">Gamepad</a></h1>
<p>You can get a handle to the gamepad input state with <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/fn.input.html"><code>gamepad::input()</code></a>. With
this, you can get an iterator of the connected gamepads and their <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/struct.GamepadId.html">IDs</a> with <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/struct.Gilrs.html#method.gamepads"><code>gamepad::input().gamepads()</code></a>.</p>
<p>Using a <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/struct.Gamepad.html"><code>Gamepad</code></a>, which can also be obtained from
<a href="https://docs.rs/sge/latest/sge/prelude/gamepad/struct.Gilrs.html#method.gamepad"><code>gamepad::input().gamepad(id)</code></a>, you can query the state of the buttons and
sticks using the methods on the <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/struct.Gamepad.html"><code>Gamepad</code></a> struct.</p>
<p>Importantly:</p>
<ul>
<li><code>.right_stick</code>, <code>.left_stick</code>, and <code>.d_pad</code> for getting the input of
sticks/dpad as a vector.</li>
<li><code>.is_pressed</code> for checking if a
<a href="https://docs.rs/sge/latest/sge/prelude/gamepad/enum.Button.html"><code>gamepad::Button</code></a>
is pressed</li>
</ul>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/gamepad/index.html">gamepad module</a></p>
<p>See also:
<a href="https://github.com/LilyRL/sge/blob/master/examples/gamepad.rs"><code>/examples/gamepad.rs</code></a>
for an example on how to use the API, and to test if your controller is being
recognised properly.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="time"><a class="header" href="#time">Time</a></h1>
<p>You can use <code>time()</code> to get the time the program has been running in seconds,
and <code>delta_time()</code> to get the time since last frame in seconds.</p>
<p>There is also <code>physics_time()</code> and <code>physics_delta_time()</code> which uses the
‘physics timer’. The physics timer can be sped up, slowed down, and paused using
<code>set_physics_speed</code>, <code>pause_physics_timer</code> and <code>play_physics_timer</code>. This
isn’t related to the physics system, and wont speed it up.</p>
<p>There are also some convenience methods you can use, like <code>once_per_second</code> or
<code>once_per_n_seconds</code> which only returns true once every some timeframe, and
<code>oscillate</code> which moves between two values once per second, <code>oscillate_t</code> lets
you provide your own time value, so you can speed it up or whatever.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/time/index.html">time module</a> for
full list of functions</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="drawing-text"><a class="header" href="#drawing-text">Drawing text</a></h1>
<p>There are 3 types of text drawing functions:</p>
<ul>
<li><code>draw_text_*</code>: for basic text drawing.</li>
<li><code>draw_multiline_text_*</code>: for properly drawing text with newlines in it.</li>
<li><code>draw_wrapped_text_*</code>: for drawing text with a max width, that wraps when it
gets to the edge.</li>
</ul>
<p>There are also equivalent functions for measuring the area text will take up
when drawn. These shouldn’t be too slow as a cache is maintained internally.</p>
<p>There are functions for drawing text quickly, which only take the text and
position, and draw with the default monospaced font. You can use <code>draw_text_ex</code>
and <code>draw_text_custom</code> to specify the font used, text color, and more.</p>
<h2 id="fonts"><a class="header" href="#fonts">Fonts</a></h2>
<p>Fonts can be loaded with
<a href="https://docs.rs/sge/latest/sge/prelude/text/fn.create_ttf_font.html"><code>create_ttf_font</code></a>.</p>
<p>SGE comes with <a href="https://www.jetbrains.com/lp/mono/">JetBrains Mono</a> as it’s
default font, and when the <code>extra_fonts</code> feature is enabled (by default), also 5
variants of the <a href="https://rsms.me/inter/">Inter</a> typeface, for regular, bold,
italic, bold italic, and display. These are availible as the constants <code>MONO</code>,
<code>SANS</code>, <code>SANS_BOLD</code>, <code>SANS_ITALIC</code>, <code>SANS_BOLD_ITALIC</code>, and <code>SANS_DISPLAY</code>.</p>
<p>If you experience stuttering when drawing text, you can pre-populate the cache
of letters.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>font_ref.populate_font_cache(&Font::latin_character_list(), 24);
<span class="boring">}</span></code></pre>
<p>You can also specify the filtering methods of the font texture.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>font.use_linear_filtering();
font.use_nearest_filtering();
<span class="boring">}</span></code></pre>
<h2 id="typeface"><a class="header" href="#typeface">Typeface</a></h2>
<p>The <code>Typeface</code> struct groups fonts of the same typeface together so that they
can be used for things like rich text.</p>
<p><img src="text.jpg" alt="Text in action"></p>
<hr>
<p>See:
<a href="https://github.com/LilyRL/sge/blob/master/examples/text.rs"><code>/examples/text.rs</code></a>
for an example</p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/text/index.html">text module
documentation</a> for more detail.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="textures"><a class="header" href="#textures">Textures</a></h1>
<p>Textures can be loaded using one of the following:</p>
<ul>
<li><code>include_texture!</code>: Bake bytes of image file into binary, and load them from that. This comes with the benefit of working without using any outside files from the executable, meaning you only need to give someone one file to play your game.</li>
<li><code>load_texture_sync</code>: synchronously load texture from file path.</li>
<li><code>load_texture_from_bytes_sync</code>: synchronously load texture from bytes.</li>
<li><code>load_texture</code>: asynchronously load texture from file path.</li>
<li><code>load_texture_from_bytes</code>: asynchronously load texture from bytes.</li>
</ul>
<p>All of these functions return a <code>TextureRef</code>, which is just a wrapper around an integer, and can be passed around/copied at almost 0 cost. This reference is also guaranteed to always be valid, so long as you don’t use any of the <code>unsafe</code> functions associated with <code>Ref</code> types.</p>
<p>You can inspect the total number of currently tracked textures in the engine by calling <code>num_registered_textures()</code>.</p>
<p>Textures can be drawn by using one of the following:</p>
<ul>
<li><code>draw_texture(_world)</code>: simply draws a texture at some position at some scale.</li>
<li><code>draw_texture_scaled(_world)</code>: allows you to draw the texture at any scale, without respecting the original aspect ratio.</li>
<li><code>draw_texture_ex</code>: contains additional options like an arbitrary transform, tint, and the option to only draw a region of the whole texture.</li>
</ul>
<p>Apart from loading raw files, you can manage textures using the following methods:</p>
<ul>
<li><code>SgeTexture::empty(width, height)</code>: Allocates a blank, uninitialized texture container on the GPU with the specified pixel dimensions.</li>
<li><code>SgeTexture::from_engine_image(image)</code>: Converts an in-memory <code>Image</code> struct directly into an uploadable texture layout.</li>
<li><code>download_to_image(&self)</code>: Downloads pixel data from the GPU back into an accessible CPU-side <code>Image</code>. This supports both float and unsigned byte formats with three or four color components, and automatically maps raw byte streams back into standard pixel collections.</li>
</ul>
<p>Example of advanced texture drawing from <a href="https://github.com/LilyRL/sge/blob/master/examples/demo.rs#L127"><code>demo.rs</code></a>:</p>
<p><img src="textures.jpg" alt="two textures, one with custom transform and a blue tint"></p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/textures/index.html">texture module documentation</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="audio"><a class="header" href="#audio">Audio</a></h1>
<p>Sounds can be loaded using one of the following:</p>
<ul>
<li><code>include_sound!</code>: Bake bytes of sound file into binary, and load them from
that. This comes with the benefit of working without using any outside files
from the executable, meaning you only need to give someone one file to play
your game.</li>
<li><code>load_sound_sync</code>: synchronously load sound from file path.</li>
<li><code>load_sound_from_bytes_sync</code>: synchronously load sound from bytes.</li>
<li><code>load_sound</code>: asynchronously load sound from file path.</li>
<li><code>load_sound_from_bytes</code>: asynchronously load sound from bytes.</li>
</ul>
<p>All of these functions return a <code>SoundRef</code>, which is just a wrapper around an
integer, and can be passed around/copied at almost 0 cost. This reference is
also guaranteed to always be valid, so long as you don’t use any of the <code>unsafe</code>
functions associated with <code>Ref</code> types.</p>
<p>Sounds can be played in one of two ways:</p>
<ol>
<li>
<p><code>play_sound</code>: simply plays a sound reference without blocking.</p>
</li>
<li>
<p><code>play_sound_ex</code>: plays a sound and returns a <code>SoundBuilder</code> object, allowing
you to add effects to the sound before playing with <code>.start()</code>.</p>
<p>Here is an example of how you might use this:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>play_sound_ex(sound)
.fade_in(Duration::from_millis(800))
.volume(0.5)
.start();
<span class="boring">}</span></code></pre>
<p>You can find a list of effects in the <a href="https://docs.rs/sge/latest/sge/prelude/audio/struct.SoundBuilder.html"><code>SoundBuilder</code> documentation</a>.</p>
</li>
</ol>
<hr>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/simple_sound.rs"><code>/examples/simple_sound.rs</code></a></p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/audio/index.html">sound module documentation</a></p>
<p>See also:
<a href="https://github.com/LilyRL/sge/blob/master/examples/space_game.rs"><code>/examples/space_game.rs</code></a>
for a game with sound effects.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="camera"><a class="header" href="#camera">Camera</a></h1>
<h2 id="2d"><a class="header" href="#2d">2D</a></h2>
<p>The 2D camera controls how objects are drawn in world space. You can get access
to the camera with <code>get_camera_2d</code> and <code>get_camera_2d_mut</code>, and use the methods
on the Camera2D object to move around, zoom in and out, rotate, and more.</p>
<p>The provided functions <code>world_to_screen</code>, and <code>screen_to_world</code> can be helpful,
for example to find the position of the cursor in world space, instead of screen space.</p>
<p>See: <a href="https://docs.rs/sge_camera/latest/sge_camera/d2/struct.Camera2D.html"><code>Camera2D</code> documentation</a></p>
<h2 id="3d"><a class="header" href="#3d">3D</a></h2>
<p>You can get access to the camera with <code>get_camera_2d</code> and <code>get_camera_2d_mut</code>,
and use the methods on it to move around, change the FOV, and change between a
perspective and isometric projection.</p>
<p>See: <a href="https://docs.rs/sge_camera/latest/sge_camera/d3/struct.Camera3D.html"><code>Camera3D</code> documentation</a></p>
<h2 id="controllers"><a class="header" href="#controllers">Controllers</a></h2>
<p>Camera controllers can be used to easily let the user controller the camera,
without having to implement it from scratch. Camera controllers are used by
creating a mutable instance of the struct once, and calling <code>.update()</code> on it
every frame.</p>
<pre class="playground"><code class="language-rust">#[main("Game")]
fn main() {
let mut controller = PanningCameraController::new();
loop {
controller.update();
// rest of game logic
}
}</code></pre>
<h3 id="2d-1"><a class="header" href="#2d-1">2D</a></h3>
<p>The 2D camera supports the following camera controllers:</p>
<ul>
<li><a href="https://docs.rs/sge/latest/sge/prelude/camera/struct.PanningCameraController.html"><code>PanningCameraController</code></a>:
Allows the user to (optionally) pan and zoom the camera using the scroll wheel, and a
customizable button (defaults to left click).</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/camera/struct.CameraShakeController.html"><code>CameraShakeController</code></a>:
allows for easy shaking of the camera, by using <code>.add_trauma(amount: f32)</code>.</li>
</ul>
<h3 id="3d-1"><a class="header" href="#3d-1">3D</a></h3>
<p>The 3D camera supports the following camera controllers:</p>
<ul>
<li><a href="https://docs.rs/sge/latest/sge/prelude/camera/struct.OrbitCameraController.html"><code>OrbitCameraController</code></a>:
Allows the user to orbit the camera around a point and zoom in and out, with
many configuration options.</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/camera/struct.FirstPersonCameraController.html"><code>FirstPersonCameraController</code></a>:
Allows the user to look around in the first person, using the mouse.</li>
</ul>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/camera/index.html">camera module documentation</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="3d-2"><a class="header" href="#3d-2">3D</a></h1>
<p>The support for 3D is less fleshed out than for 2D at the moment, but it is
being worked on.</p>
<p>The workflow for 3D is different to 2D, as it would be too inefficient to
rebuild 3D meshes every frame, so they are retained. You can create a 3D mesh
from a .obj file. Instead of using a set flat/textured/patterned material like
in 2D, you can use any shader/material you want on 3D objects. There are built-in
functions for creating generic flat/physically shaded materials of different
colors, or you can create your own.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let program = include_program!(
"./material_shader/outline_vertex.glsl",
"./material_shader/outline_fragment.glsl"
)?;
let material = Material::new(program)
.with_color("outline_color", Color::PURPLE_100)
.with_float("outline_width", 0.3)
.create();
let object = Object3D::from_obj_bytes_with_material(
include_bytes!("../assets/models/suzanne.obj"),
material,
)?;
<span class="boring">}</span></code></pre>
<p>Objects then need to be drawn every frame with <code>object.draw()</code>.</p>
<p><img src="material.jpg" alt="Outline material suzanne showcase"></p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/d3/index.html">3D module documentation</a></p>
<h2 id="materials"><a class="header" href="#materials">Materials</a></h2>
<p>A material is just a collection of a vertex shader, fragment shader, and named
uniforms. Uniforms can be set using <code>material.set_*</code>, and can be used to pass
data from the CPU into the shader.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let threshold = (time * 0.2).sin() * 0.5 + 0.5;
mat.set_float("dissolve_threshold", threshold);
<span class="boring">}</span></code></pre>
<pre><code class="language-c">#version 150
in vec3 v_normal;
in vec3 v_position;
in vec2 v_tex_coords;
in vec3 v_world_position;
out vec4 color;
uniform float time;
uniform float dissolve_threshold; // used here
</code></pre>
<p>There are some uniforms that are set automatically by the engine, and are
availible in all material shaders:</p>
<ul>
<li><code>view_proj_matrix</code> mat4</li>
<li><code>model_matrix</code> mat4</li>
<li><code>normal_matrix</code> mat3</li>
<li><code>time</code> in seconds, float</li>
<li><code>delta_time</code> in seconds, float</li>
<li><code>random</code> number to use as a seed, float</li>
<li><code>screen_size</code> in pixels, vec2</li>
<li><code>camera_pos</code> vec3</li>
</ul>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/rendering/struct.Material.html"><code>Material</code> documentation</a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/material.rs"><code>/examples/material.rs</code></a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/material_shader/vertex.glsl"><code>/examples/material_shader/vertex.glsl</code></a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/material_shader/fragment.glsl"><code>/examples/material_shader/fragment.glsl</code></a></p>
<h2 id="shapes-1"><a class="header" href="#shapes-1">Shapes</a></h2>
<p>In addition to loading shapes from an object, there are also functions for
creating simple shapes from some parameters. So far there are only:</p>
<ul>
<li><code>cubiod</code>/<code>cube</code> (also <code>_from_extents</code> and <code>_with_orientation</code>)</li>
<li><code>line_3d</code> and <code>line_3d_flat</code></li>
<li><code>cube_wireframe</code> and <code>cube_wireframe_flat</code></li>
</ul>
<p>Example from <a href="https://github.com/LilyRL/sge/blob/master/examples/shapes_3d.rs"><code>shapes_3d.rs</code></a>:</p>
<p><img src="shapes_3d.jpg" alt="cube within cube wireframe"></p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/d3/index.html"><code>3D module documentation</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="some-rendering-details"><a class="header" href="#some-rendering-details">Some rendering details</a></h1>
<p>2D rendering works in layers. When you use <code>new_draw_queues()</code> or use a
post-processing effect, a new set of draw queues will be created, meaning that anything new that is drawn will be
drawn over everything drawn previously, no matter what.</p>
<p>In the case of a
post-processing effect this is almost always what you want, but if it isn’t you
may need to be careful of what order your drawing functions run. If this is a
problem for you, decouple your update functions from drawing functions that
don’t mutate state, so that drawing functions can run in any order.</p>
<p>Within a single draw queue, objects drawn in screen-space will always be drawn
above objects drawn in world space. You can overwrite this using a new set of
draw queues.</p>
<h2 id="scissors"><a class="header" href="#scissors">Scissors</a></h2>
<p>A scissor is basically a filter to a rectangle of the screen, it will prevent
rendering of any pixels outside of that rectangle for the duration of that
scissor being active. You can add and remove them with <code>push_scissor</code> and
<code>pop_scissor</code>. Pushing a scissor when another scissor is already active will set
the scissor to the intersection of both of them, so things will only be drawn
if they are inside both rectangles.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// this will draw a semi-circle
push_scissor(Area::new(vec2(window_center().x, 0.0), window_size()).to_rect());
draw_circle(window_center(), 500.0, Color::WHITE);
pop_scissor();
<span class="boring">}</span></code></pre>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="async"><a class="header" href="#async">Async</a></h1>
<p>Using an <code>async</code> main function and <code>next_frame().await</code> allows SGE to run coroutines.</p>
<h2 id="coroutines"><a class="header" href="#coroutines">Coroutines</a></h2>
<p>A coroutine is a function that can pause execution and resume later. Coroutines do not return a value. They run alongside the main loop on the same thread and update every frame.</p>
<p>When a coroutine calls <code>.await</code> on a future, it pauses. At the end of the frame, SGE updates all active coroutines. If the future is ready, the coroutine continues executing.</p>
<pre class="playground"><code class="language-rust">use sge::*;
#[main("Title")]
async fn main() -> anyhow::Result<()> {
// Start a coroutine from an async function
let coroutine = start_coroutine(count());
loop {
if coroutine.is_done() {
draw_text("Done", Vec2::ZERO);
}
if should_quit() {
break;
}
// next_frame().await updates engine systems and advances running coroutines
next_frame().await;
}
Ok(())
}
// Draws numbers from 0 to 99, incrementing each frame
async fn count() {
for i in 0..100 {
draw_text(i, Vec2::ZERO);
// Pauses this function until the next frame
next_frame().await;
}
}</code></pre>
<p>You can use coroutines for tasks that span multiple frames, like cutscenes or timed events. Track the status of a coroutine using coroutine.is_done().</p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/coroutines.rs"><code>/examples/coroutines.rs</code></a></p>
<h2 id="other-async-functions"><a class="header" href="#other-async-functions">Other async functions</a></h2>
<p>SGE also has some other async functions worth knowing about, such as ones to wait
a certain amount of time, and for <a href="https://lilyrl.github.io/sge/fs.html">loading resources</a> from disk/bytes in the
background so it doesn’t interrupt the user by freezing the program while it’s loading.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// Pause for 2.5 seconds
wait_for(2.5).await;
// Pause for 10 frames
wait_for_frames(10).await;
<span class="boring">}</span></code></pre>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/exec/index.html">Exec module</a></p>
<h2 id="the-main-macro"><a class="header" href="#the-main-macro">The main macro</a></h2>
<p>The <code>#[main()]</code> macro is just a helper that makes it more simple to initialize
the engine. All it does is replace:</p>
<pre class="playground"><code class="language-rust">#[main("Window title")]
async fn main() {
// do stuff
}</code></pre>
<p>With:</p>
<pre class="playground"><code class="language-rust">fn main() {
sge::init("Window title").unwrap();
sge::run_async(async {
// do stuff
});
}</code></pre>
<p><code>init</code> creates the window and sets everything up. <code>run_async</code> sets up an asynchronous
environment for your code to run in, and makes sure it is updated once per frame.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="window"><a class="header" href="#window">Window</a></h1>
<p>There are <a href="https://docs.rs/sge/latest/sge/prelude/window/index.html">numerous
functions</a> for
querying and changing the properties of the window, for example if it is
in fullscreen or how big it is in pixels.</p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/window/index.html">window module documentation</a></p>
<h2 id="cursor-icons"><a class="header" href="#cursor-icons">Cursor icons</a></h2>
<p>You may set the current cursor icon to use with one of <a href="https://docs.rs/sge/latest/sge/prelude/cursor_icons/index.html">these
functions</a>, it
will only last for one frame, so you should re-set the cursor icon every frame.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// in frame loop/function called every frame
if is_hovered {
use_pointer_cursor_icon();
}
<span class="boring">}</span></code></pre>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="debugging"><a class="header" href="#debugging">Debugging</a></h1>
<p>SGE comes with a set of tools for measuring performance and resource usage,
useful for checking for any inefficiencies or memory leaks.</p>
<p>There are functions for checking performance directly.</p>
<ul>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.avg_fps.html"><code>avg_fps</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.max_fps.html"><code>max_fps</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.min_fps.html"><code>min_fps</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_draw_calls.html"><code>get_draw_calls</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_drawn_objects.html"><code>get_drawn_objects</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_engine_time.html"><code>get_engine_time</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_index_count.html"><code>get_index_count</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_max_draw_calls.html"><code>get_max_draw_calls</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_max_drawn_objects.html"><code>get_max_drawn_objects</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_max_engine_time.html"><code>get_max_engine_time</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_max_index_count.html"><code>get_max_index_count</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_max_vertex_count.html"><code>get_max_vertex_count</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/debugging/fn.get_vertex_count.html"><code>get_vertex_count</code></a></li>
</ul>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/debugging/index.html">debugging module</a></p>
<p>There are also some built-in debug visualisations such as drawing a window,
using the engine’s built-in UI library, that shows graphs of the number of
vertices/indices drawn and lots of other information.</p>
<p>Use <code>draw_debug_info</code> for graphs, or <code>draw_simple_debug_info</code> for just numbers
(better performance).</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/debug_visualisations/index.html">debug visualisations module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="rich-text"><a class="header" href="#rich-text">Rich Text</a></h1>
<p>Rich text supports rendering multiple styles, colors, sizes, and formatting modes inside a single text object.</p>
<p>You can construct rich text manually from <code>RichTextBlocks</code>, or parse it from a lightweight HTML-like syntax using <code>rich_text(str)</code>.</p>
<p>Parsing performs tokenization + style tree construction, so avoid reparsing every frame. Parse once and reuse the resulting <code>RichText</code>.</p>
<p>Quotes around argument values are optional as long as the value does not
contain spaces (e.g. #abc).</p>
<pre><code class="language-html"><font size=50>
This text is <font color=red3>red</font>,
and this text is <font color=blue3>blue</font>
<font color=#abc>
You <font size=30>may make your</font> text any
</font>
<font color="rgb 1.0 1.0 1.0">
color <hl color=slate9>you want</hl>
</font>
<font bold color="oklch 0.7 0.1184 119">
Check the docume
</font>
<font italic color=blue2>
ntation for
</font>
<b>rich_text()</b> for more.
<i>
Lorem <ol color=green5>ipsum dolor</ol>
<ul>sit amet consectetur</ul>
adipiscing elit.
</i>
<ul color=red5>
You <st>can</st> nest
<font color=red5 size=70 bold>styles</font>
<noul>inside</noul>
of eachother
</ul>
</font>
</code></pre>
<p><img src="rich_text.jpg" alt="How this rich text looks when rendered"></p>
<p>Rich text can be drawn with <code>.draw</code> or <code>.draw_world</code>, and the text will be
wrapped within the area provided, and printed to stdout (the terminal), with
most of the formatting applied.</p>
<div class="table-wrapper">
<table>
<thead>
<tr><th>Tag</th><th>Information</th><th>Supported arguements</th></tr>
</thead>
<tbody>
<tr><td><b> <bold> <strong></td><td>Makes the text inside of it</td><td>None</td></tr>
<tr><td><i> <italic> <em></td><td>Makes the text inside italic</td><td>None</td></tr>
<tr><td><font></td><td>More complex styling like font size</td><td>size, color, bold, italic, underline, strikethrough, outline highlight</td></tr>
<tr><td><ul> <underline></td><td>Specifies an underline for text inside</td><td>color</td></tr>
<tr><td><st> <strikethrough></td><td>Specifies strikethrough for text inside</td><td>color</td></tr>
<tr><td><nost> <no-strikethrough></td><td>Removes strikethrough for text inside</td><td>None</td></tr>
<tr><td><hl> <highlight> <bg></td><td>Specifies a background fill for the text inside</td><td>color</td></tr>
<tr><td><nohl> <nobg> <no-highlight></td><td>Removes highlight for text inside</td><td>None</td></tr>
<tr><td><ol> <outline></td><td>Specifies an outline around the text inside</td><td>color</td></tr>
<tr><td><noul> <no-underline></td><td>Removes underline for text inside</td><td>None</td></tr>
</tbody>
</table>
</div>
<p>Argument values can unquoted when the argument has no spaces.</p>
<pre><code class="language-html"><font color=red5>
<font color="#abc">
<font color="rgb 1.0 1.0 1.0">
</code></pre>
<p>Rich text can also be printed to stdout with <code>.print_to_stdout()</code>, and will
retain most of the formatting in the terminal. If it looks weird, check if your
terminal supports true color.</p>
<p>Rich text is used by the logging system.</p>
<hr>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/rich_text.rs"><code>/examples/rich_text.rs</code></a></p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/text/fn.rich_text.html"><code>rich_text</code></a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="logging"><a class="header" href="#logging">Logging</a></h1>
<p>SGE provides a <a href="https://docs.rs/log/latest/log/">log</a> backend, that can be
optionally drawn to the screen and printed to stdout.</p>
<p><code>draw_logs()</code> can be used to draw all the logs to the screen as rich text, when wanted.</p>
<p><img src="logs.jpg" alt="Logs drawn in-game"></p>
<p>Messages can be logged out using the included standard <code>log</code> macros. Shown in
descending order of importance:</p>
<ul>
<li><a href="https://docs.rs/sge/latest/sge/prelude/logging/macro.error.html"><code>error!</code></a>
for logging out critical errors. Shown by default.</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/logging/macro.warn.html"><code>warn!</code></a> for
logging out things that may be errors or indications of a bug, but do not stop
the program from working. Shown by default.</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/logging/macro.info.html"><code>info!</code></a> for
logging out useful information. Shown by default.</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/logging/macro.debug.html"><code>debug!</code></a>
for logging out debug info messages. Not shown by default.</li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/logging/macro.trace.html"><code>trace!</code></a> for
logging out very minor information that could be useful for tracking down a
bug. Not shown by default.</li>
</ul>
<p>The minimum log level can be set with
<a href="https://docs.rs/sge/latest/sge/prelude/logging/fn.set_min_log_level.html"><code>set_min_log_level</code></a>,
to show only logs equal to or more important than some log level, or disabled entirely.</p>
<p>The logger has multiple verbosity levels that can be configured
using <a href="https://docs.rs/sge/latest/sge/prelude/logging/fn.set_logger_verbosity.html"><code>set_logger_verbosity</code></a>.</p>
<p>Logs will be printed to the terminal by default.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/logging/index.html">logging module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="file-system-api"><a class="header" href="#file-system-api">File System API</a></h1>
<p>SGE provides functions to interact with the file system that integrate with the
engine’s <code>async</code> system, so that you can read/write to files in the background,
while showing a loading screen for the user. This includes functions for loading
resources like textures, where the image decoding will be done on another thread.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/fs/index.html">FS module</a></p>
<p>See also: <a href="https://github.com/LilyRL/sge/blob/master/examples/async_asset_loading.rs"><code>/examples/async_asset_loading.rs</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="rng"><a class="header" href="#rng">RNG</a></h1>
<p>Most games need random numbers. You can generate them with these functions:</p>
<ul>
<li>
<p><code>get_next_counter</code>: returns 0 the first time you call it, returns the number
one more than the last time you called it on all following times</p>
</li>
<li>
<p><code>rand</code>: generic function that returns a random value of the type you pass it, as
long as that type supports random generation.</p>
</li>
<li>
<p><code>rand_bool</code>: Return a bool with a probability p of being true.</p>
</li>
<li>
<p><code>rand_choice</code>: returns a random element from an array, if the array is empty it panics.</p>
</li>
<li>
<p><code>maybe_rand_choice</code>: returns none if choices are empty, returns random choice otherwise</p>
</li>
<li>
<p><code>rand_color</code>: returns a random color</p>
</li>
<li>
<p><code>rand_f32</code>: generates f32 between -1 and 1</p>
</li>
<li>
<p><code>rand_range</code>: generates a random number between two values</p>
</li>
<li>
<p><code>rand_ratio</code>: return a bool with a probability of numerator/denominator of being true.</p>
</li>
<li>
<p><code>rand_usize</code>: returns a random usize</p>
</li>
<li>
<p><code>rand_vec2</code>: returns a random vec2</p>
</li>
<li>
<p><code>rand_vec3</code>: returns a random vec3</p>
</li>
<li>
<p><code>rand_vec4</code>: returns a random vec4</p>
</li>
<li>
<p><code>id!()</code>: returns a constant random number. baked at compile time, won’t change
each time it is run, but will change if it is used in multiple places. This
will make more sense if you know how macros work in Rust.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>id!() != id!();
let mut numbers = vec![];
for _ in 0..5 {
numbers.push(id!());
}
// every number in numbers is equal
<span class="boring">}</span></code></pre>
</li>
</ul>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/rng/index.html">rng module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="image-api"><a class="header" href="#image-api">Image API</a></h1>
<p><a href="https://docs.rs/sge/latest/sge/prelude/image/struct.Image.html"><code>Image</code></a>s are
like textures, but stored on the CPU. Images can be loaded and parsed
from image files like <code>.png</code> and <code>.jpg</code>, and their contents can be manipulated
by indexing into the buffer directly or using the many methods on the
<a href="https://docs.rs/sge/latest/sge/prelude/image/struct.Image.html"><code>Image</code></a> struct
to draw shapes.</p>
<p>Unlike when GPU rendering, working with an <code>Image</code> requires you to use the
<a href="https://docs.rs/sge_color/latest/sge_color/u8/union.ColorU8.html"><code>ColorU8</code></a>
type, which uses u8 values for (r,g,b,a), that range from 0 to 255,
where white is (255,255,255,255). <code>ColorU8</code> can be converted to <code>Color</code> and vice
versa with <code>.to_color</code> and <code>.to_color_u8</code>.</p>
<p>An image can be uploaded to a GPU texture with
<a href="https://docs.rs/sge/latest/sge/prelude/textures/struct.SgeTexture.html#method.from_engine_image"><code>SgeTexture::from_enginen_image</code></a>
and a GPU texture can be downloaded to an image with <code>texture.download_to_image()</code>.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/image/index.html">image module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="math-api"><a class="header" href="#math-api">Math API</a></h1>
<p>SGE exposes a fork of <a href="https://docs.rs/bevy_math/latest/bevy_math/"><code>bevy_math</code></a>
with lots of useful types and functions for math/linear algebra.</p>
<p>You can see a list of the included items
<a href="https://docs.rs/sge/latest/sge/prelude/math/index.html">here</a>. I would
recommend looking through the documentation for
<a href="https://docs.rs/sge/latest/sge/prelude/math/struct.Vec2.html">Vec2</a> at least as
it is used everywhere.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="particle-system"><a class="header" href="#particle-system">Particle System</a></h1>
<p>Create a particle system with <code>ParticleSystem::new()</code>, and spawn emitters or one
shot particle spawners when needed, then run <code>.update()</code> and <code>.draw()</code> or
<code>.draw_world()</code> once per frame to see the particles onscreen. You can customize
lots of parameters to change how the particles act.</p>
<pre class="playground"><code class="language-rust">#[main("Particles")]
fn main() {
let mut particles = ParticleSystem::new();
let batch = ParticleOneshot::builder()
.shape(&Rect::new_square(Vec2::ZERO, 20.0, Color::YELLOW_500))
.size_randomness(5.0)
.color_randomness(Color::new(0.3, 0.1, 0.1))
.direction_randomness(0.5)
.speed(40.0)
.speed_randomness(3.0)
.rotation_speed_randomness(0.2)
.end_color(Color::RED_700)
.acceleration(vec2(0.0, 1.0))
.acceleration_randomness(vec2(0.0, 0.2))
.lifetime(2.0)
.quantity(100)
.build();
loop {
if should_spawn_particles {
particles.spawn_oneshot(&batch, position)
}
particles.update();
particles.draw();
if should_quit() {
break;
}
next_frame().await;
}
}</code></pre>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/particles/index.html">particles module</a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/particles.rs"><code>/examples/particles.rs</code></a></p>
<p>See also:
<a href="https://github.com/LilyRL/sge/blob/master/examples/space_game.rs"><code>/examples/space_game.rs</code></a>
for a more complex example of how particles can be used.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="persistence-api"><a class="header" href="#persistence-api">Persistence API</a></h1>
<p>When making a game or application you will inevitably want to store some kind of
state between launches, so that you aren’t starting from scratch each time you
run the program. SGE provides a simple high-performance interface to make this easier.</p>
<p>To use the persistence API, create a state struct, and annotate it with the
<code>#[persistent]</code> attribute macro.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>#[persistent]
struct State {
score: u64,
player_color: Color,
enemy_state: EnemyState,
}
#[persistent]
struct EnemyState {
health: f32,
position: Vec2,
}
<span class="boring">}</span></code></pre>
<p>The persistent macro will generate the functions <code>state.save(path)</code>,
<code>State::load(path)</code>, <code>state.to_bytes()</code>, and <code>State::from_bytes(bytes)</code>, for any
struct that has fields that are all also serializable.</p>
<p>Serializable types include:</p>
<ul>
<li>Most builtin Rust types, numbers, strings, etc.</li>
<li>Anything supported by <code>rkyv</code> out of the box.</li>
<li>Most of the SGE types you would want to use this with
<ul>
<li>Vectors</li>
<li>Both colour types</li>
</ul>
</li>
<li>Any other custom struct you write, as long as it is also decorated with <code>#[persistent]</code></li>
</ul>
<h2 id="performance"><a class="header" href="#performance">Performance</a></h2>
<p>This uses <a href="https://docs.rs/rkyv/latest/rkyv/"><code>rkyv</code></a> under the hood, which
performs zero-copy serialization, meaning that it is very fast, so you can save
often if you want. Do not save/load every frame.</p>
<hr>
<p>See <a href="https://docs.rs/sge/latest/sge/prelude/persistence/triat.Persistent.html"><code>Persistent</code> trait</a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/persistence.rs"><code>/examples/persistence</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="physics-api"><a class="header" href="#physics-api">Physics API</a></h1>
<p>The physics API is based on <a href="https://docs.rs/rapier2d/latest/rapier2d/"><code>rapier2d</code></a>.</p>
<p>Create a <a href="https://docs.rs/sge/latest/sge/prelude/physics/struct.PhysicsWorld.html"><code>PhysicsWorld</code></a> with <code>PhysicsWorld::new()</code>. This returns a <code>WorldRef</code> that you call <code>.update()</code> on each frame to step the simulation.</p>
<p>Rapier2D uses positive y up, but SGE uses positive y down, so coordinates
converted before being returned, so that the position in the world can be the
same as the position onscreen. A conversion rate of 100 pixels per Rapier2D
meter is used.</p>
<pre class="playground"><code class="language-rust">#[main("Physics")]
fn main() {
let mut world = PhysicsWorld::new();
loop {
world.update();
if should_quit() {
break;
}
next_frame().await;
}
}</code></pre>
<h2 id="creating-objects"><a class="header" href="#creating-objects">Creating Objects</a></h2>
<p>There are three types of physics objects:</p>
<ul>
<li><strong>Dynamic</strong>: affected by gravity and forces, collides with everything.</li>
<li><strong>Fixed</strong>: immovable, used for walls, floors, and static geometry.</li>
<li><strong>Kinematic</strong>: moved manually (e.g. via <code>set_position</code>), but participates in collision detection.</li>
</ul>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let dynamic_obj = world.create_dynamic(Bounds::Circle(20.0));
let wall = world.create_fixed(Bounds::Rect(Vec2::new(1000.0, 50.0)));
let platform = world.create_kinematic(Bounds::Rect(Vec2::new(200.0, 20.0)));
<span class="boring">}</span></code></pre>
<p>Each of these also has a <code>_with</code> variant that accepts a <code>ColliderConfig</code> for customizing physical material properties:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let bouncy = world.create_dynamic_with(
Bounds::Circle(15.0),
ColliderConfig::default()
.restitution(0.9)
.friction(0.1)
.density(2.0),
);
<span class="boring">}</span></code></pre>
<p>Objects can be removed with <code>.remove()</code>.</p>
<p>Once created, objects can be manipulated using the methods on the <code>ObjectRef</code> struct.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let obj = world
.create_dynamic(Bounds::Circle(15.0))
.with_position(Vec2::new(200.0, 100.0))
.with_velocity(Vec2::new(150.0, 0.0))
.with_ccd(); // continuous collision detection
// Reading state
let pos = obj.get_position();
let vel = obj.get_velocity();
let rot = obj.get_rotation(); // all rotations are in radians
let mass = obj.get_mass();
obj.set_position(Vec2::new(300.0, 200.0));
obj.set_velocity(Vec2::new(0.0, -100.0));
obj.set_rotation(std::f32::consts::PI * 0.25);
obj.add_velocity(Vec2::new(50.0, 0.0));
obj.add_force(Vec2::new(0.0, -500.0));
obj.move_by(Vec2::new(5.0, 0.0));
obj.set_angvel(2.0); // rad/s
obj.add_angvel(0.5);
<span class="boring">}</span></code></pre>
<h2 id="bounds"><a class="header" href="#bounds">Bounds</a></h2>
<p><code>Bounds</code> describes the shape of a collider. The available variants are:</p>
<ul>
<li><code>Bounds::Circle(radius)</code></li>
<li><code>Bounds::Rect(Vec2)</code>: full size from center</li>
<li><code>Bounds::Capsule { half_height, radius }</code>: vertical capsule</li>
<li><code>Bounds::CapsuleX { half_width, radius }</code>: horizontal capsule</li>
<li><code>Bounds::Triangle(a, b, c)</code>: relative to the object’s position</li>
<li><code>Bounds::ConvexHull(points)</code>: computed from a point cloud</li>
<li><code>Bounds::Polyline(points)</code>: a series of connected line segments, useful for terrain</li>
<li><code>Bounds::Line { a, b }</code></li>
<li><code>Bounds::Compound(children)</code>: multiple shapes combined, each with an offset</li>
</ul>
<h2 id="sensors"><a class="header" href="#sensors">Sensors</a></h2>
<p>Sensors are not physical objects, other objects will pass right through them,
but they still check if something is colliding with them.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let sensor = world
.create_fixed_with(Bounds::Circle(80.0), ColliderConfig::default().sensor(true))
.with_position(Vec2::new(400.0, 300.0));
if sensor.is_colliding() {
// something is inside the sensor
}
<span class="boring">}</span></code></pre>
<h2 id="collisions"><a class="header" href="#collisions">Collisions</a></h2>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>if obj.is_colliding() { ... }
if obj.is_colliding_with(other) { ... }
if let Some(points) = obj.check_collision_with(other) {
let normal = points.normal;
let depth = points.depth;
}
for info in obj.collisions() {
let other: ObjectRef = info.other;
let normal: Vec2 = info.points.normal;
match info.event {
CollisionType::Started => { /* wasn't colliding last frame, colliding now */ }
CollisionType::Ongoing => { /* colliding last frame, still colliding now */ }
CollisionType::Stopped => { /* was colliding last frame, not anymore */ }
}
}
<span class="boring">}</span></code></pre>
<h2 id="world-settings"><a class="header" href="#world-settings">World Settings</a></h2>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>world.set_gravity(980.0); // in pixels/world units, so 9.8 will be very slow
let g = world.get_gravity();
<span class="boring">}</span></code></pre>
<h2 id="debug-visualization"><a class="header" href="#debug-visualization">Debug Visualization</a></h2>
<p>You can draw outlines of all colliders and collision normals for debugging:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>world.draw_colliders();
// or
world.draw_colliders_world();
<span class="boring">}</span></code></pre>
<p>Colliders are drawn in red, objects currently in collision are highlighted in yellow with arrows showing the collision normals.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/physics/index.html">physics module</a></p>
<p>See also: <a href="https://github.com/LilyRL/sge/blob/master/examples/physics.rs"><code>/examples/physics.rs</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="post-processing-effects"><a class="header" href="#post-processing-effects">Post-processing effects</a></h1>
<p>You can apply post processsing effects onto the screen with one of the following functions:</p>
<ul>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.bloom_screen.html"><code>bloom_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.blur_screen.html"><code>blur_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.brighten_screen.html"><code>brighten_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.chromatic_abberation_screen.html"><code>chromatic_abberation_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.contrast_screen.html"><code>contrast_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.film_grain_screen.html"><code>film_grain_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.greyscale_screen.html"><code>greyscale_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.hue_rotate_screen.html"><code>hue_rotate_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.invert_screen.html"><code>invert_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.pixelate_screen.html"><code>pixelate_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.saturate_screen.html"><code>saturate_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.sharpen_screen.html"><code>sharpen_screen</code></a></li>
<li><a href="https://docs.rs/sge/latest/sge/prelude/post_processing/fn.vignette_screen.html"><code>vignette_screen</code></a></li>
</ul>
<p>These effects will be applied to everything that has already been rendered out
on the screen, but not anything that was rendered afterwards. This will also
create new draw queues.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/post_processing/index.html">post processing module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="render-textures"><a class="header" href="#render-textures">Render Textures</a></h1>
<p>You may for whatever reason want to render to a texture instead of the screen,
you can do this with render textures, which are just a collection of a normal color texture and depth
texture.</p>
<p>You can create a texture with <code>create_empty_render_texture()</code>.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let size = UVec2::new(50, 50);
let render_texture = create_empty_render_texture(size.x, size.y)?;
loop {
clear_screen(Color::BLACK);
// any drawing functions run after this function will draw to the texture
// instead of the screen. you don't need to pass anything extra into them.
// be careful to always call end_rendering_to_texture().
// i would recommend to reduce the chance of bugs that you never call end_rendering
// in a different part of the code as start.
start_rendering_to_texture(render_texture);
// actually clearing texture
clear_screen(Color::WHITE);
draw_square(vec2(10.0, 10.0), 50.0, Color::SKY_500);
end_rendering_to_texture();
if should_quit() {
break;
}
next_frame().await;
}
<span class="boring">}</span></code></pre>
<p>Some use cases to consider:</p>
<ul>
<li>Using a lower resolution for a retro-effect, but with better performance than
drawing at full resolution and then using <code>pixelate_screen()</code>.</li>
<li>Splitscreen multiplayer, draw once for each player to textures, and then
position them on the screen.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="advanced-shapes"><a class="header" href="#advanced-shapes">Advanced Shapes</a></h1>
<p>Shapes that cannot be represented by vertices (i.e.: have smooth edges, like
circles), are drawn using <a href="https://en.wikipedia.org/wiki/Signed_distance_function">signed distance
functions</a>, this means
that they are drawn exactly, no matter how much you zoom in.</p>
<p>You can access the signed distance function object directly to specify
additional effects like a drop shadow, corner radius, or a patterned fill.</p>
<p>For example:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let object = Sdf::pentagram(c, 50.0)
.with_fill(Color::RED_500, Color::RED_400, 0.0, 5.0, SdfFill::Grid)
.with_corner_radius(5.0)
.with_stroke(2.0, Color::RED_200, SdfStroke::Outside)
.with_shadow(vec2(10.0, 10.0), 10.0, Color::NEUTRAL_900);
draw_sdf(object);
<span class="boring">}</span></code></pre>
<p>Here is a sample of the shapes, patterns and effects possible (from the SDF example).</p>
<hr>
<p><img src="sdf.jpg" alt="SDF showcase"></p>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/sdf/index.html">SDF module</a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/sdf.rs"><code>/exampes/sdf.rs</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="storage-api"><a class="header" href="#storage-api">Storage API</a></h1>
<p>Games often have a lot of unrelated systems running in parallel. This can lead
to lots of confusing code to manage the state of all the different parts of your
code, and extra effort to make state availible to the functions that need to
read/mutate it.</p>
<p>In complex projects, you may choose to use the storage API to mitigate this
complexity, at the cost of it being less clear what parts of the code could be
mutating state.</p>
<p>The storage API lets you store and retrieve custom state structs from a global
store. Just create a unique state type, and use <code>storage_init_state</code> to store
it, and <code>storage_get_state</code> and <code>storage_get_state_mut</code> to retrieve it. You can
have a max of one store per type, so if you need to store a single <code>bool</code>, for
example, create a struct wrapper around the boolean value before storing it.</p>
<pre class="playground"><code class="language-rust">struct MyState {
score: usize,
}
fn main() {
// ...
let state = MyState { score: 0 };
storage_store_state(state);
// ...
}
fn show_score(pos: Vec2) {
let state = storage_get_state::<MyState>();
draw_text(state.score.to_string(), pos);
}</code></pre>
<p>There are some other functions you may want to do with storage listed <a href="https://docs.rs/sge/latest/sge/prelude/storage/index.html">here</a>.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/storage/index.html">storage module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="ui"><a class="header" href="#ui">UI</a></h1>
<p>Finally… I’ve been waiting a long time to write this chapter. This is the #1
best part of the engine, no contest. THE USER INTERFACE LIBRARY!!!</p>
<p>The UI library is split into 2 sections. There is a library of <code>base</code> unstyled
elements that you can use to create more complex user interfaces of any style,
and a set of styles widgets from a few categories, at the moment there is <code>flat</code>
(the most comprehensive), <code>material</code> (meant to mimic Google Material UI 3;
supports theming), and <code>w95</code> (meant to mimic Windows 95, not really updated).</p>
<p>Complex layouts can be created by combining the basic <code>base</code>
components in a nested arrangement. The base components are designed to be as
simple as possible so as to be very flexible and be able to be used for many
different things by combining them with other elements. For example, instead of
a single <code>div</code> element like in HTML, there are smaller simpler elements for
adding a fill, adding a border, centering an element, adding padding, etc.</p>
<p>Base elements are designed to be as flexible as possible. For example, the
slider element allows you to create the bar and handle from other UI elements,
meaning you can have it look however you want. For an example of how this works,
check the <a href="https://docs.rs/sge_ui/1.1.4/src/sge_ui/library/flat/slider.rs.html#8">source code for the flat slider</a></p>
<p>The UI is immediate mode, which makes it much simpler to use, as you don’t have
to tell the UI that some value has changed, you just pass in the true value
every frame and it updates instantly. Since the UI is rebuilt every frame, you
need some way of retaining state from one frame to the next, like the position
of a floating window, this is done by using unique IDs for UI elements. The
easiest way to do this is by using the <code>id!()</code> macro, which will give you a
unique but constant random number. You can see this being used around the UI
examples. If you need to create a derivative ID from an existing ID, for example
when creating a complex component that needs multiple stateful widgets, use
<code>original_id ^ id!()</code> (that’s an XOR), to create a new unique ID that is based
on the original one.</p>
<blockquote>
<p>“The best way to learn about something is to see and use it for yourself”</p>
<p>-Sun Tzu</p>
</blockquote>
<p>Thanks Sun, for this reason, I will point you to the <code>ui_showcase</code> example. If
you dont remember how to run examples, check the introduction chapter. This
example has a list of every UI element, and shows them in action. I would
reccomend you look through this with the code for the example open in another
window to see how everything is used. The source code is <a href="https://github.com/LilyRL/sge/blob/master/examples/ui_showcase.rs">here</a>.</p>
<p>Here’s an awful looking screenshot from the <code>ui</code> example.</p>
<p><img src="ui.jpg" alt="Showcase of ui elements"></p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/ui/index.html">ui module</a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="multiplayer"><a class="header" href="#multiplayer">Multiplayer</a></h1>
<p>Multiplayer netcode for video games can be really hard to write. SGE has a
system to make this task easier.</p>
<p>First, create a state struct to hold the data you want associated with each
player. This struct must implement <code>Clone</code>, and be annotated with
<code>#[persistent(diff)]</code>. The diff is to allow the multiplayer system to tell what
part of the struct changed between updates, so it can efficiently only send
what’s necessary.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>#[derive(Clone)]
#[persistent(diff)]
struct State {
position: Vec2,
}
<span class="boring">}</span></code></pre>
<p>Then create a <code>MultiplayerState<T></code> object with the default instance of the
struct, a username, and room name. Your player will be connected to all other
players in the same room, so make sure that it is, at least, unique to the video
game you are developing by adding some random characters at the top for all
rooms part of your game.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let mut state = MultiplayerState::new(
State {
position: Vec2::ZERO,
},
"Lily".to_string(),
"YOUR_GAME_NAME_1897".to_string(),
);
<span class="boring">}</span></code></pre>
<p>From this point, you can call <code>state.update()</code>, at a rate of your choosing. I
would recommend not sending it too often as this is bad for performance and will
use more bandwidth, I would recommend 10 or 20 times a second.</p>
<pre class="playground"><code class="language-rust">// 10 times a second
const UPDATE_RATE: f32 = 0.1;
fn main() -> anyhow::Result<()> {
// ...
loop {
// ...
if once_per_n_seconds(UPDATE_RATE) {
state.update()?;
}
}
}</code></pre>
<p>You can access your state (i.e. the state of the player) with
<code>state.your_state()</code>, <code>state.your_state_mut()</code>, <code>state.your_username()</code>, and
<code>state.your_user_data()</code>. You can get the states of other users with
<code>state.other_users()</code>, <code>state.get_user()</code>, and <code>state.get_user_mut()</code>. Note that
any changes you make to other users states will not be reflected for other
people, and will be updated by new data from that user changing their own state.</p>
<p>In your cleanup (end of main function), it is best to add this code:</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>state.disconnect();
// so it has time to send the disconnect message before the process is killed
std::thread::sleep(Duration::from_millis(50));
<span class="boring">}</span></code></pre>
<p>This will tell all other clients in the room that you have disconnected, and
will remove that user from their list of users, so they won’t still show up as a
frozen player in game.</p>
<h2 id="interpolation"><a class="header" href="#interpolation">Interpolation</a></h2>
<p>If you create something like this:</p>
<pre class="playground"><code class="language-rust">struct State {
position: Vec2,
}
const UPDATE_RATE: f32 = 0.1;
#[main("Multiplayer")]
fn main() {
let mut state = MultiplayerState::new(
State {
position: Vec2::ZERO,
},
"Lily".to_string(),
"YOUR_GAME_NAME_1897".to_string(),
);
loop {
// add controls for user to move around, and update the state periodically
for (_, user) in state.other_users().iter() {
draw_circle_world(user.position, 50.0, Color::RED_500);
}
// ...
}
}</code></pre>
<p>…you will notice that people jump around on screen in large intervals, because
their positions are being updated at a rate less than the frame rate. To fix
this, without reducing performance, we can use interpolation. You can implement
interpolation manually using the history of previous state values stored in
<code>UserData</code>, or use the builtin automatic interpolation. To use automatic
interpolation, you need to annotate the state struct with <code>#[persistent(diff, lerp)]</code> instead.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>#[derive(Clone)]
#[persistent(diff, lerp)]
struct State {
position: Vec2,
}
<span class="boring">}</span></code></pre>
<p>This will implement <code>PartialLerp</code> for that type, which interpolates only the
fields that can be interpolated (<code>f32</code>, <code>f64</code>, <code>Vec2</code>, <code>Vec3</code>, <code>Vec4</code>, <code>Color</code>).
With this, on types that implement <code>PartialLerp</code>, you can use something like
this instead, for smooth interpolation without suttering even at low update rates.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>const UPDATE_RATE: f32 = 0.1;
const INTERPOLATION_DELAY: f32 = UPDATE_RATE * 2.0; // can add more for more reliability; 2*update-rate is standard
// ...
// render target time is the time in the past we should pretend it is,
// and interpolate based on updates we have gotten from the future (aka present)
let render_target_time = time() - INTERPOLATION_DELAY;
for (_, user) in state.other_users().iter() {
if let Some(interpolated_state) = user.current_lerped(render_target_time) {
draw_circle_world(user.position, 50.0, Color::RED_500);
}
}
<span class="boring">}</span></code></pre>
<h2 id="notifications"><a class="header" href="#notifications">Notifications</a></h2>
<p>If you want to communicate directly with other clients, for example when adding
a chat system to your game, you can use notifications. Send a notification with
<code>state.send_notification(data)</code>, and recieve with <code>state.drain_notifications()</code>.
The data sent in a notification is a <code>Vec<u8></code>,
allowing you to send any data you want in any form. You could do this by
reserving the first number in the series as a type specifier, and interpreting
the rest of the sequence based on the parsed type. Remember that you can convert
any type annotated with <code>#[persistent]</code> to bytes with <code>.to_bytes()</code>, and convert
strings to and from bytes with <code>string.as_bytes()</code> and <code>String::from_utf8()</code>.</p>
<pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let mut state = MultiplayerState::new(...);
let mut messages = vec![];
for notification in state.drain_notifications() {
let Some(user) = other_state.get_user(notification.user_id) else {
break;
};
let username = &user.username;
let text = String::from_utf8(notification.data).unwrap();
messages.push(text);
}
let message = "hello".to_string();
state.send_notification(message.as_bytes().to_vec());
<span class="boring">}</span></code></pre>
<h2 id="backends"><a class="header" href="#backends">Backends</a></h2>
<p>The multiplayer system is generic over a backend. The default backend,
<code>IttyBackend</code>, uses <a href="https://ittysockets.com/">itty-sockets</a> to transmit data,
but any struct that implements <code>MultiplayerBackend</code> can be used, for example you
could write one that sends data over the LAN instead. The <code>MultiplayerBackend</code>
interface is quite websocket/stream centered, but could easily be made to work
with a database instead; anything that will broadcast received messages to all
connected users and supports separate rooms will work.</p>
<hr>
<p>See: <a href="https://docs.rs/sge/latest/sge/prelude/multiplayer/index.html">multiplayer module</a></p>
<p>See: <a href="https://github.com/LilyRL/sge/blob/master/examples/multiplayer.rs"><code>/examples/multiplayer.rs</code></a></p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="platform-support"><a class="header" href="#platform-support">Platform Support</a></h1>
<p>SGE uses OpenGL, so GPU support is near universal.</p>
<p>I test on Linux and it is guarenteed to work there. I tried to test on Windows
but I couldn’t get networking working on Windows to clone the codebase and I
can’t be bothered really. There’s no reason why it shouldn’t work. If you try it
on Windows and it fails, please submit an issue and I’ll do my best to fix it.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<template id=fa-eye><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M288 32c-80.8 0-145.5 36.8-192.6 80.6C48.6 156 17.3 208 2.5 243.7c-3.3 7.9-3.3 16.7 0 24.6C17.3 304 48.6 356 95.4 399.4C142.5 443.2 207.2 480 288 480s145.5-36.8 192.6-80.6c46.8-43.5 78.1-95.4 93-131.1c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C433.5 68.8 368.8 32 288 32zM432 256c0 79.5-64.5 144-144 144s-144-64.5-144-144s64.5-144 144-144s144 64.5 144 144zM288 192c0 35.3-28.7 64-64 64c-11.5 0-22.3-3-31.6-8.4c-.2 2.8-.4 5.5-.4 8.4c0 53 43 96 96 96s96-43 96-96s-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6z"/></svg></span></template>
<template id=fa-eye-slash><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M38.8 5.1C28.4-3.1 13.3-1.2 5.1 9.2S-1.2 34.7 9.2 42.9l592 464c10.4 8.2 25.5 6.3 33.7-4.1s6.3-25.5-4.1-33.7L525.6 386.7c39.6-40.6 66.4-86.1 79.9-118.4c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C465.5 68.8 400.8 32 320 32c-68.2 0-125 26.3-169.3 60.8L38.8 5.1zM223.1 149.5C248.6 126.2 282.7 112 320 112c79.5 0 144 64.5 144 144c0 24.9-6.3 48.3-17.4 68.7L408 294.5c5.2-11.8 8-24.8 8-38.5c0-53-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6c0 10.2-2.4 19.8-6.6 28.3l-90.3-70.8zm223.1 298L373 389.9c-16.4 6.5-34.3 10.1-53 10.1c-79.5 0-144-64.5-144-144c0-6.9 .5-13.6 1.4-20.2L83.1 161.5C60.3 191.2 44 220.8 34.5 243.7c-3.3 7.9-3.3 16.7 0 24.6c14.9 35.7 46.2 87.7 93 131.1C174.5 443.2 239.2 480 320 480c47.8 0 89.9-12.9 126.2-32.5z"/></svg></span></template>
<template id=fa-copy><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M502.6 70.63l-61.25-61.25C435.4 3.371 427.2 0 418.7 0H255.1c-35.35 0-64 28.66-64 64l.0195 256C192 355.4 220.7 384 256 384h192c35.2 0 64-28.8 64-64V93.25C512 84.77 508.6 76.63 502.6 70.63zM464 320c0 8.836-7.164 16-16 16H255.1c-8.838 0-16-7.164-16-16L239.1 64.13c0-8.836 7.164-16 16-16h128L384 96c0 17.67 14.33 32 32 32h47.1V320zM272 448c0 8.836-7.164 16-16 16H63.1c-8.838 0-16-7.164-16-16L47.98 192.1c0-8.836 7.164-16 16-16H160V128H63.99c-35.35 0-64 28.65-64 64l.0098 256C.002 483.3 28.66 512 64 512h192c35.2 0 64-28.8 64-64v-32h-47.1L272 448z"/></svg></span></template>
<template id=fa-play><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg></span></template>
<template id=fa-clock-rotate-left><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M75 75L41 41C25.9 25.9 0 36.6 0 57.9V168c0 13.3 10.7 24 24 24H134.1c21.4 0 32.1-25.9 17-41l-30.8-30.8C155 85.5 203 64 256 64c106 0 192 86 192 192s-86 192-192 192c-40.8 0-78.6-12.7-109.7-34.4c-14.5-10.1-34.4-6.6-44.6 7.9s-6.6 34.4 7.9 44.6C151.2 495 201.7 512 256 512c141.4 0 256-114.6 256-256S397.4 0 256 0C185.3 0 121.3 28.7 75 75zm181 53c-13.3 0-24 10.7-24 24V256c0 6.4 2.5 12.5 7 17l72 72c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-65-65V152c0-13.3-10.7-24-24-24z"/></svg></span></template>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr-ef4e11c1.min.js"></script>
<script src="mark-09e88c2c.min.js"></script>
<script src="searcher-c2a407aa.js"></script>
<script src="clipboard-1626706a.min.js"></script>
<script src="highlight-abc7f01d.js"></script>
<script src="book-a0b12cfe.js"></script>
<!-- Custom JS scripts -->
<script>
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</div>
</body>
</html>
