From daa4e52b37d7208e55b8226a781bb5fc8c46b84f Mon Sep 17 00:00:00 2001
From: "Jill \"oatmealine\" Monoids" <oatmealine@disroot.org>
Date: Mon, 19 Sep 2022 21:33:41 +0300
Subject: [PATCH] aft support; add actorframe/actorscroller notes

---
 MANUAL.md    | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 src/main.lua |  2 +-
 template     |  2 +-
 3 files changed, 97 insertions(+), 3 deletions(-)

diff --git a/MANUAL.md b/MANUAL.md
index 93bb876..41ede6d 100644
--- a/MANUAL.md
+++ b/MANUAL.md
@@ -25,6 +25,9 @@ Uranium Template originally formed during the creation of a currently unreleased
 - [How do I start writing code?](#how-do-i-start-writing-code)
 - [Defining actors](#defining-actors)
   - [Initializing actors](#initializing-actors)
+  - [Actor-specific notes](#actor-specific-notes)
+    - [`ActorFrameTexture`](#actorframetexture)
+    - [`ActorFrame`, `ActorScroller`](#actorframe-actorscroller)
 - [Callback usage](#callback-usage)
   - [Default callbacks](#default-callbacks)
     - [`uranium.update(dt: number)`](#uraniumupdatedt-number)
@@ -89,6 +92,7 @@ Uranium Template originally formed during the creation of a currently unreleased
 - [Examples](#examples)
   - [Default Uranium Template code](#default-uranium-template-code)
   - [Simple platformer base](#simple-platformer-base)
+  - [AFTs](#afts)
 - [Credits](#credits)
 
 ## Testimonies
@@ -187,6 +191,51 @@ sprite:addcommand('Init', function(self)
 end)
 ```
 
+### Actor-specific notes
+
+#### `ActorFrameTexture`
+
+AFTs work in the same way as usual AFTs do in terms of ordering: they capture everything that was drawn to the screen before them:
+
+```lua
+quad:Draw() -- will be drawn to the AFT
+
+aft:Draw()
+
+sprite:Draw() -- will not be drawn to the AFT
+```
+
+See [the AFT example](#afts) for a quick setup to play around with. The ability to dynamically adjust at which point in the stack they render makes them _a lot_ more powerful than you'd expect.
+
+#### `ActorFrame`, `ActorScroller`
+
+Due to Uranium Template's recursive actor loader, these are impossible to implement in a meaningful way. Actors are loaded in a manner like so:
+
+```lua
+local actor1 = Quad()
+local actor2 = Sprite()
+local actor3 = BitmapText()
+```
+
+```xml
+<Layer Type="ActorFrame"/>
+<children>
+  <Layer Type="Quad"/>
+  <Layer Type="ActorFrame"/>
+  <children>
+    <Layer Type="Sprite"/>
+    <Layer Type="ActorFrame"/>
+    <children>
+      <Layer Type="BitmapText"/>
+    </children>
+  </children>
+</children>
+```
+
+This is a technical limitation; NotITG does not allow loading a dynamic amount of arbitrary actors defined via Lua in any way other than this (as far as I know). Meaning, if you defined an `ActorFrame` or `ActorScroller`, you would not be able to add anything to its' children.
+
+However, if you're looking to do what `ActorFrame` does, the standard library `transform` module can handle that for you! (NYI)
+
 ## Callback usage
 
 Uranium uses a unique callback system - to define a callback, you define a function under `uranium.` with your desired callback name:
@@ -624,7 +673,6 @@ function uranium.update(dt)
 
   -- for the text, get a rainbow color
   local col = shsv(t * 0.6, 0.5, 1)
-  print(col)
   text:diffuse(col:unpack()) -- the :unpack() is necessary when passing into :diffuse()
   -- wag the text
   text:rotationz(math.sin(t * 2) * 10)
@@ -698,6 +746,52 @@ function uranium.update(dt)
 end
 ```
 
+### AFTs
+
+_VSync recommended_
+
+```lua
+local coverQuad = Quad()
+coverQuad:diffuse(0, 0, 0, 1)
+coverQuad:xywh(scx, scy, sw, sh)
+
+local testQuad = Quad()
+testQuad:zoom(50)
+
+local aft = ActorFrameTexture()
+
+local aftSprite = Sprite()
+oat.sprite(aftSprite)
+aftSprite:diffusealpha(0.99)
+aftSprite:zoom(1.01)
+aftSprite:rotationz(0.2)
+
+aft:addcommand('Init', function(self)
+  oat.aft(aft) -- put this here; else it'll recreate it every frame!
+  aftSprite:SetTexture(self:GetTexture())
+end)
+
+local text = BitmapText('common', 'uranium template!')
+text:xy(scx, scy)
+
+function uranium.update(dt)
+  coverQuad:Draw()
+
+  aftSprite:Draw()
+
+  local rainbow = shsv(t * 1.2, 0.5, 1)
+
+  testQuad:xy((vectorFromAngle(t * 160, 100) + vector(scx, scy)):unpack())
+  testQuad:diffuse(rainbow:unpack())
+  testQuad:zoom(50 * math.random())
+  testQuad:Draw()
+
+  aft:Draw()
+
+  text:Draw()
+end
+```
+
 ## Credits
 
 **XeroOl** - Mirin Template was a massive design inspiration; early stages of this template borrowed lots of code from it<br>
diff --git a/src/main.lua b/src/main.lua
index 200bea8..c5d03cc 100644
--- a/src/main.lua
+++ b/src/main.lua
@@ -31,6 +31,7 @@ function uranium.update(dt)
   -- no need to reset properties - uranium resets all properties that you set upon definition!
 
   -- throw in the logo aswell, because why not
+  -- zoom and glow is done for a quick-and-dirty outline
   sprite:zoom(sprite:GetZoom() * 1.1)
   sprite:glow(1, 1, 1, 1)
   sprite:Draw()
@@ -40,7 +41,6 @@ function uranium.update(dt)
 
   -- for the text, get a rainbow color
   local col = shsv(t * 0.6, 0.5, 1)
-  print(col)
   text:diffuse(col:unpack()) -- the :unpack() is necessary when passing into :diffuse()
   -- wag the text
   text:rotationz(math.sin(t * 2) * 10)
diff --git a/template b/template
index d5e2b0c..34fac4a 160000
--- a/template
+++ b/template
@@ -1 +1 @@
-Subproject commit d5e2b0c252b0e41ba8e314dd6fdf4c84362ed214
+Subproject commit 34fac4aa998198205cc930ee6cb19d9a5b01974e