What is all this

- Begin work on API concept reference page

Author: Jozufozu

docs/.vitepress/config.ts

@@ -1,6 +1,6 @@
 // noinspection JSUnusedGlobalSymbols
 
-import { defineConfig } from "vitepress";
+import {defineConfig} from "vitepress";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -56,8 +56,9 @@ export default defineConfig({
       "/flywheel/api": [
         {
           text: "Flywheel API",
+          link: "/flywheel/api/",
           items: [
-            { text: "Index", link: "/flywheel/api" },
+            {text: "Concept Reference", link: "/flywheel/api/concepts"},
             { text: "GLSL API", link: "/flywheel/api/glsl-api" },
           ]
         },

docs/flywheel/api/concepts.md

@@ -0,0 +1,48 @@
+# Concept Reference
+
+The Flywheel API has a few key differences from vanilla rendering that are important to understand.
+
+This page serves as a reference for concepts unique to Flywheel.
+
+[[toc]]
+
+## Game Objects
+
+A game object is an Entity, BlockEntity, or Effect in the level. This is not a unique concept to Flywheel, but Flywheel
+provides a unified rendering path for all game objects.
+
+### Effects
+
+An effect is a "free" game object. It is a concept unique to Flywheel and as such does not exist on the server.
+Effects allow users of Flywheel to access the Flywheel rendering system without needing to depend on a BlockEntity or
+Entity. The caveat is that the implementor of an Effect is responsible for managing its own lifecycle and
+client/server synchronization.
+
+## Visuals
+
+Visuals are the analog to Renderers in vanilla Minecraft. Each Entity/BlockEntity/Effect that is rendered will have a
+corresponding Visual. This way, Visuals can maintain state independent of the client representation of the game object,
+and update in parallel to other Visuals of the same type.
+
+Statefulness and parallelism are the core motivation behind this abstraction.
+
+## Instances
+
+An Instance is a single renderable object that is uploaded to the GPU. Visuals create, update, and delete Instances.
+
+Instances are stateful. If an Instance is not updated, it will continue to be rendered in its existing configuration,
+without being re-uploaded to the GPU. This allows for significant performance improvements and CPU->GPU bandwidth
+savings when Instances do not move (e.g. in the case of BlockEntities), or when the animation can be expressed in the
+instance shader.
+
+Users of Flywheel are encouraged to only update Instances when necessary.
+
+## Render Origin
+
+The render origin is an integer coordinate in world space which serves as the origin for rendering.
+
+This is different from vanilla entity/block entity rendering which uses the camera position as the origin.
+Such an approach is not viable for Flywheel, as that would require every instance to update every frame. Instead,
+Flywheel maintains a render origin that is nearby, but not necessarily exactly at, the camera position. As the camera
+moves in the level Flywheel will update the render origin once it gets too far away. All instances are deleted and all
+visuals are recreated when the render origin updates.

docs/flywheel/api/index.md

@@ -1,10 +1,4 @@
----
-description: Documentation related to Flywheel's API.
-
-next: false
----
-
-# API Docs {#api-docs}
+# Flywheel API
 
 This section of the wiki has information that is useful for developers wanting to interact with Flywheel in any way.