Fix flw_hideLightningFlashesOption and update docs

- Add uniforms to glsl api docs
- Expand on api concepts

Author: Jozufozu

common/src/backend/resources/assets/flywheel/flywheel/internal/uniforms/options.glsl

@@ -15,5 +15,5 @@ layout(std140) uniform _FlwOptionsUniforms {
     uint flw_textBackgroundForChatOnlyOption;
     float flw_darknessPulsingOption;
     float flw_damageTiltOption;
-    uint hideLightningFlashesOption;
+    uint flw_hideLightningFlashesOption;
 };

docs/flywheel/api/concepts.md

@@ -20,11 +20,17 @@ 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,
+Visuals are the analog to Renderers in vanilla Minecraft. Each game object that is rendered will have a
+corresponding Visual object. 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.
+Statefulness and parallelism are the core motivations behind this abstraction.
+
+::: danger IMPLEMENTATION CONTRACT
+Your Visual _must_ be in a correct state upon construction, where all created Instances are be at their expected
+position. The most common bug when implementing Visuals is having your instances appear at the render origin.
+:::
 
 ## Instances
 
@@ -37,6 +43,11 @@ instance shader.
 
 Users of Flywheel are encouraged to only update Instances when necessary.
 
+::: warning
+Ensure you `.delete()` all Instances you create when your Visual is deleted. Failure to do so will result in orphaned
+instances that continue to be rendered.
+:::
+
 ## Render Origin
 
 The render origin is an integer coordinate in world space which serves as the origin for rendering.
@@ -46,3 +57,25 @@ Such an approach is not viable for Flywheel, as that would require every instanc
 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.
+
+::: tip
+To map from world space to render space, subtract the render origin from the world space position. e.g.
+
+```java
+BlockPos renderSpacePos = worldSpacePos.subtract(visualizationContext.renderOrigin());
+```
+
+:::
+
+## Plans
+
+Plans are Flywheel's way to expose the thread pool to Visuals. Plans are created once, and executed many times.
+When executed, Plans receive a generic context object, a reference to the Executor they're running on, and a Runnable
+to call when all the work in the Plan is complete. This simple abstraction allows for incredibly complex composition
+of tasks and allows for easy parallelization of work.
+
+Implementing `DynamicVisual` and `TickableVisual` requires you to construct Plans that will be executed every frame or
+tick, respectively.
+
+_Most_ Visuals will not need the full complexity of Plans, so the Flywheel lib provides `Simple` counterparts to both
+interfaces.

docs/flywheel/api/glsl-api.md

@@ -12,9 +12,24 @@ Some functions/variables are only available for specific shader stages.
 
 ::: code-group
 
-<<< snippets/common.glsl
-<<< snippets/material.glsl
-<<< snippets/vertex.glsl
-<<< snippets/fragment.glsl
+<<< stage/common.glsl
+<<< stage/material.glsl
+<<< stage/vertex.glsl
+<<< stage/fragment.glsl
+
+:::
+
+### Uniforms
+
+In addition to the stage-specific variables above, every stage has access to the following uniforms.
+All uniforms are included in the prelude and do not have to be manually included.
+
+::: code-group
+
+<<< uniforms/fog.glsl
+<<< uniforms/frame.glsl
+<<< uniforms/level.glsl
+<<< uniforms/options.glsl
+<<< uniforms/player.glsl
 
 :::

docs/flywheel/api/snippets/common.glsl renamed to docs/flywheel/api/stage/common.glsl

@@ -0,0 +1,3 @@
+vec4 flw_fogColor;
+vec2 flw_fogRange;
+int flw_fogShape;

docs/flywheel/api/snippets/fragment.glsl renamed to docs/flywheel/api/stage/fragment.glsl

@@ -0,0 +1,54 @@
+struct FrustumPlanes {
+    vec4 xyX;// <nx.x, px.x, ny.x, py.x>
+    vec4 xyY;// <nx.y, px.y, ny.y, py.y>
+    vec4 xyZ;// <nx.z, px.z, ny.z, py.z>
+    vec4 xyW;// <nx.w, px.w, ny.w, py.w>
+    vec2 zX;// <nz.x, pz.x>
+    vec2 zY;// <nz.y, pz.y>
+    vec2 zZ;// <nz.z, pz.z>
+    vec2 zW;// <nz.w, pz.w>
+};
+
+FrustumPlanes flw_frustumPlanes;
+
+mat4 flw_view;
+mat4 flw_viewInverse;
+mat4 flw_viewPrev;
+mat4 flw_projection;
+mat4 flw_projectionInverse;
+mat4 flw_projectionPrev;
+mat4 flw_viewProjection;
+mat4 flw_viewProjectionInverse;
+mat4 flw_viewProjectionPrev;
+
+ivec3 flw_renderOrigin;
+vec3 flw_cameraPos;
+vec3 flw_cameraPosPrev;
+vec3 flw_cameraLook;
+vec3 flw_cameraLookPrev;
+vec2 flw_cameraRot;
+vec2 flw_cameraRotPrev;
+
+vec2 flw_viewportSize;
+float flw_aspectRatio;
+float flw_defaultLineWidth;
+float flw_viewDistance;
+
+uint flw_ticks;
+float flw_partialTick;
+float flw_renderTicks;
+float flw_renderSeconds;
+float flw_systemSeconds;
+uint flw_systemMillis;
+
+/** 0 means no fluid. Use FLW_CAMERA_IN_FLUID_* defines to detect fluid type. */
+uint flw_cameraInFluid;
+/** 0 means no block. Use FLW_CAMERA_IN_BLOCK_* defines to detect block type. */
+uint flw_cameraInBlock;
+
+uint FLW_CAMERA_IN_FLUID_WATER;
+uint FLW_CAMERA_IN_FLUID_LAVA;
+uint FLW_CAMERA_IN_FLUID_UNKNOWN;
+
+uint FLW_CAMERA_IN_BLOCK_POWDER_SNOW;
+uint FLW_CAMERA_IN_BLOCK_UNKNOWN;

docs/flywheel/api/snippets/material.glsl renamed to docs/flywheel/api/stage/material.glsl

@@ -0,0 +1,35 @@
+vec4 flw_skyColor;
+vec4 flw_cloudColor;
+
+vec3 flw_light0Direction;
+vec3 flw_light1Direction;
+
+/** The current day number of the level. */
+uint flw_levelDay;
+/** The current fraction of the current day that has elapsed. */
+float flw_timeOfDay;
+
+uint flw_levelHasSkyLight;
+
+float flw_sunAngle;
+
+float flw_moonBrightness;
+/** There are normally only 8 moon phases. */
+uint flw_moonPhase;
+
+uint flw_isRaining;
+float flw_rainLevel;
+uint flw_isThundering;
+float flw_thunderLevel;
+
+float flw_skyDarken;
+
+uint flw_constantAmbientLight;
+
+/** Use FLW_DIMENSION_* ids to determine the dimension. May eventually be implemented for custom dimensions. */
+uint flw_dimension;
+
+uint FLW_DIMENSION_OVERWORLD;
+uint FLW_DIMENSION_NETHER;
+uint FLW_DIMENSION_END;
+uint FLW_DIMENSION_UNKNOWN;