Compare commits

...

18 Commits
1.0-b1 ... main

6 changed files with 203 additions and 99 deletions

277
MANUAL.md
View File

@ -24,21 +24,27 @@ 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)
- [Accessing raw actors](#accessing-raw-actors)
- [Actor-specific notes](#actor-specific-notes)
- [`ActorFrameTexture`](#actorframetexture)
- [`ActorFrame`](#actorframe)
- [`ActorScroller`](#actorscroller)
- [`BitmapText`](#bitmaptext)
- [Textures](#textures)
- [Shaders](#shaders)
- [Callback usage](#callback-usage)
- [Default callbacks](#default-callbacks)
- [`uranium.update(dt: number)`](#uraniumupdatedt-number)
- [`uranium.init()`](#uraniuminit)
- [`uranium.ready()`](#uraniumready)
- [`uranium.exit()`](#uraniumexit)
- [`uranium.focus(hasFocus: boolean)`](#uraniumfocushasfocus-boolean)
- [`update(dt: number)`](#updatedt-number)
- [`init()`](#init)
- [`ready()`](#ready)
- [`exit()`](#exit)
- [`focus(hasFocus: boolean)`](#focushasfocus-boolean)
- [Custom callbacks](#custom-callbacks)
- [Requiring files](#requiring-files)
- [Configuration](#configuration)
- [`uranium.config.resetOnFrameStart(bool: boolean)`](#uraniumconfigresetonframestartbool-boolean)
- [`uranium.config.resetActorOnFrameStart(actor: Actor, bool: boolean?)`](#uraniumconfigresetactoronframestartactor-actor-bool-boolean)
- [`uranium.config.hideThemeActors(bool: boolean)`](#uraniumconfighidethemeactorsbool-boolean)
- [Standard library](#standard-library)
- [Importing modules](#importing-modules)
- [`vector2D`](#vector2d)
@ -86,8 +92,8 @@ Uranium Template originally formed during the creation of a currently unreleased
- [`input.keyboardEquivalent`](#inputkeyboardequivalent)
- [`input.getInput(i: string, pn: number | nil): number`](#inputgetinputi-string-pn-number--nil-number)
- [`input.isDown(i: string, pn: number | nil): number`](#inputisdowni-string-pn-number--nil-number)
- [`uranium.press(input: inputType, pn: number)`](#uraniumpressinput-inputtype-pn-number)
- [`uranium.release(input: inputType, pn: number)`](#uraniumreleaseinput-inputtype-pn-number)
- [`press(input: inputType, pn: number)`](#pressinput-inputtype-pn-number)
- [`release(input: inputType, pn: number)`](#releaseinput-inputtype-pn-number)
- [A note about keyboard inputs](#a-note-about-keyboard-inputs)
- [`bitop`](#bitop)
- [`scheduler`](#scheduler)
@ -120,9 +126,11 @@ Uranium Template originally formed during the creation of a currently unreleased
- [`rng:jump(): void`](#rngjump-void)
- [`rng:longJump(): void`](#rnglongjump-void)
- [`ease`](#ease)
- [`players`](#players)
- [`profiler`](#profiler)
- [`util`](#util)
- [`aft`](#aft)
- [`noautplay`](#noautplay)
- [`noautoplay`](#noautoplay)
- [`eternalfile`](#eternalfile)
- [`uwuify`](#uwuify)
- [Examples](#examples)
@ -163,7 +171,7 @@ Afterwards, it should be safe to zip everything up and send it over!
`main.lua` is the entry-point for your code! From there, you can do the following:
- [Define some actors](#defining-actors), and [call initialization methods on those actors](#initializing-actors) to set them up
- [Define callbacks](#callback-usage), such as the [update](#uraniumupdatedt-number) callback
- [Define callbacks](#callback-usage), such as the [update](#updatedt-number) callback
- [Require more files in](#requiring-files)! Splitting your code into neat little modules is always good practice.
- Make use of the expansive [standard library](#standard-library), like the [vector](#vector2d) or [color](#color) classes
@ -196,31 +204,33 @@ text:rotationz(30)
text:diffuse(1, 0.8, 0.8, 1)
```
All methods that you run upon definition will be ran again at the start of every frame:
All methods that you run upon definition will be ran again at the start of every frame with `uranium.config.resetOnFrameStart`:
```lua
uranium.config.resetOnFrameStart(true)
local quad = Quad()
quad:xy(scx, scy)
quad:zoomto(60, 60)
quad:diffusealpha(1)
function uranium.update()
uranium.on('update',
-- doesn't need a reset! it'll automatically zoomto 60, 60 and set its alpha to 1
quad:Draw()
quad:zoomto(120, 120)
quad:diffusealpha(0.5)
quad:Draw()
end
end)
```
If you want to avoid this, or otherwise call getter methods, use the [`uranium.init`](#uraniuminit) callback:
If you want to avoid this for individual actors, or otherwise call getter methods, use the [`init`](#init) callback:
```lua
local sprite = Sprite()
function uranium.init()
uranium.on('init', function()
someTexture = sprite:GetTexture()
end
end)
```
Alternatively, you can also use the actors' individual `InitCommand`s:
@ -231,6 +241,35 @@ sprite:addcommand('Init', function(self)
end)
```
Or, you can disable the frame resetting functionality individually:
```lua
uranium.config.resetOnFrameStart(true)
local sprite = Sprite()
uranium.config.resetActorOnFrameStart(sprite, false)
sprite:Draw() -- will not be called per-frame
```
### Accessing raw actors
As you may have noticed, when you print an actor defined with Uranium, it won't show up as an actor - it'll show up as a "proxy" of an actor. This is because we can't actually get actors created on demand in NotITG - what happens instead is you get an object that _acts_ like an actor by calling all the same methods you pass into it, but isn't really one.
```lua
local q = Quad()
print(q) --> 'Proxy of Quad'
```
Typically, this doesn't matter; however, in certain contexts, it may be required for you to get the raw actor from a proxy actor. You can do this by accessing `__raw` on the actor - this is defined on all actors and is only available _post-initialization_.
```lua
local q = Quad()
print(q.__raw) --> nil
q:addcommand('Init', function()
print(q.__raw) --> 'Sprite (168F7F78)'
end)
```
For most things that require this, there exist simple abstractions - applying shaders has `setShader`, `setShaderfuck`, etc., however in rare circumstances this may be useful. _Please let me know if there's a use-case that I haven't accounted for!_
### Actor-specific notes
#### `ActorFrameTexture`
@ -272,13 +311,30 @@ setDrawFunction(af, function() -- necessary to call this instead of af.SetDrawFu
sprite:Draw()
end)
function uranium.update()
uranium.on('update', function()
af:Draw() -- would draw quad and sprite
end
end)
```
**Nested AFs are supported.** As with all complicated things in this template, check out the [`ActorFrame` example](#simple-actorframe-setup) for a simple working setup.
An additional extra feature Uranium Template adds to assist with rendering multiple instances is the ability to pass in arguments through `Draw()`:
```lua
setDrawFunction(af, function(x, y)
quad:xy(x, y)
quad:Draw()
end)
uranium.on('update', function()
for x = 0, 3 do
for y = 0, 3 do
af:Draw(x, y)
end
end
end)
```
#### `ActorScroller`
`ActorFrame` already has an extremely, _extremely_ complicated setup powering it in the back-end; and `ActorScroller` is way too niche for me to give it the same treatment. Sorry!
@ -299,6 +355,17 @@ However, providing custom fonts is a bit tedious due to a [vanilla bug](https://
local text = BitmapText('../src/_inter v 22px.ini', 'test')
```
#### Textures
For convinience, `Texture` is a function that will give you a `RageTexture` from a filename without the actor. Equivalent to:
```lua
local sprite = Sprite('filename.png')
sprite:hidden(1)
local texture = sprite:GetTexture()
return texture
```
### Shaders
Shaders cannot be manually defined on actors [due to a technical limitation](https://discord.com/channels/227650173256466432/666629297544495124/1022119161415077909); plus, it wouldn't make much sense to integrate them in the same way that NotITG integrates shaders with the current XML behavior. In order to give an actor a shader, you need to define them seperately:
@ -308,15 +375,13 @@ local sprite = Sprite('docs/uranium.png')
local shader = Shader('src/shader.frag') -- returns a RageShaderProgram
```
Afterwards, call `setShader` on your actor. _Using `:SetShader` will not work._
Afterwards, call `setShader` on your actor. You can call this outside of `init`, if you like.
```lua
function uranium.init()
setShader(actor, shader)
-- or
setShaderfuck(shader)
-- (don't forget to clearShaderfuck())
end
setShader(actor, shader)
-- or
setShaderfuck(shader)
-- (don't forget to clearShaderfuck())
```
If you prefer, you can also inline shader code, as long as you don't mix files with inlined code in the same shader:
@ -352,15 +417,15 @@ Check [the shader example](#shader-test) if you just want something to play arou
## Callback usage
Uranium uses a unique callback system - to define a callback, you define a function under `uranium.` with your desired callback name:
Callbacks are defined with `uranium.on`:
```lua
function uranium.update(dt)
uranium.on('update', function(dt)
-- runs every frame
end
end)
```
You can do this as many times as you like - it'll call every single function that's defined as `uranium.update`, not just the last!
You can do this as many times as you like - it'll call every single function that's defined as `update`, not just the last!
If you return a non-falsy value in a callback, however, it'll cancel every other callback after it. This can be useful for, eg. capturing inputs and ensuring they don't get passed through to other callbacks on accident.
@ -368,19 +433,19 @@ If you return a non-falsy value in a callback, however, it'll cancel every other
These are the callbacks that are built into Uranium:
#### `uranium.update(dt: number)`
#### `update(dt: number)`
Called every frame. `dt` is the time passed since the last frame, the "deltatime".
#### `uranium.init()`
#### `init()`
Called once on `OnCommand`. Every actor has been created, and the game should be starting shortly.
#### `uranium.ready()`
#### `ready()`
Fired on the first tick. A later version of `init()` where more things should be safe to use.
#### `uranium.exit()`
#### `exit()`
_Should_ call when the player exits the file. **Not properly tested yet.**
#### `uranium.focus(hasFocus: boolean)`
#### `focus(hasFocus: boolean)`
Called whenever the window loses/gains focus. You can use this to reduce render quality on alt-tab.
### Custom callbacks
@ -388,15 +453,15 @@ Called whenever the window loses/gains focus. You can use this to reduce render
Custom callbacks require no extra setup. Define your callback like usual:
```lua
function uranium.somethingHappened(value)
uranium.on('somethingHappened', function(value)
-- ...
end
end)
```
Then all you need to do to call it is:
```lua
uranium:call('somethingHappened', extra, values, go, here)
uranium.call('somethingHappened', extra, values, go, here)
```
Callbacks support as many extra values as Lua supports arguments in a function - so let's just say you won't be running out of them any time soon.
@ -422,6 +487,22 @@ Your setup would print `'hello!'`.
All [standard library](#standard-library) modules are required with `require`, see further notes in [**Importing modules**](#importing-modules).
## Configuration
Uranium Template's base functionality can be configured using `uranium.config`. You can access the raw values by requiring `uranium.config`, but this is currently undocumented.
#### `uranium.config.resetOnFrameStart(bool: boolean)`
Toggle actor resetting on frame start behavior by default. _(Default: `false`)_
#### `uranium.config.resetActorOnFrameStart(actor: Actor, bool: boolean?)`
Toggle actor resetting on frame start for individual actors. `bool` defaults to the opposite of your `resetOnFrameStart` config.
#### `uranium.config.hideThemeActors(bool: boolean)`
Toggle if theme actors (lifebars, scores, song names, etc.) are hidden. Must be toggled **before** `init`. _(Default: `true`)_
## Standard library
The Uranium Template standard library is split up into a few convinient modules. This section aims to comprehensively document them all.
@ -661,11 +742,11 @@ n:add(value)
n:reset(value)
-- then, in your update function
function uranium.update(dt)
n(dt) -- multiply this image by some value to speed it up
print(n.a) -- retrieve the eased value
print(n.toa) -- retrieve the target value it's easing towards
end
uranium.on('update', function(dt)
n:update(dt) -- multiply this image by some value to speed it up
print(n.eased) -- retrieve the eased value
print(n.target) -- retrieve the target value it's easing towards
end)
```
#### `easable(default: number): easable`
@ -674,15 +755,15 @@ Creates a new easable, setting the default to `default`. Can technically be anyt
#### `easable:set(new: number): void`
Sets the target value (`toa`) to `new`, easing the current value to the new value.
Sets the target value (`target`) to `new`, easing the current value to the new value.
#### `easable:add(new: number): void`
Equivalent to `easable:add(easable.toa + new)`.
Equivalent to `easable:add(easable.target + new)`.
#### `easable:reset(new: number): void`
Sets the current (`a`) and target (`toa`) values to `new`, **not** easing the current value to the new value.
Sets the current (`eased`) and target (`target`) values to `new`, **not** easing the current value to the new value.
#### Operations
@ -774,11 +855,11 @@ input.inputs[1][input.inputType.Left] == input.getInput('Left', 1)
Shorthand for `input.getInput(i, pn) ~= -1`. If `pn` is not provided, players are ignored and it checks if either of the players have the input held down
#### `uranium.press(input: inputType, pn: number)`
#### `press(input: inputType, pn: number)`
Called when a player presses on a certain key.
#### `uranium.release(input: inputType, pn: number)`
Same as [`uranium.press`](#uraniumpressinput-inputtype), except for releasing a key.
#### `release(input: inputType, pn: number)`
Same as [`press`](#pressinput-inputtype), except for releasing a key.
#### A note about keyboard inputs
@ -824,7 +905,7 @@ Schedules a function to run in a specific amount of time. `when` is in seconds.
#### `scheduler.scheduleInTicks(when: number, func: function): number`
Schedules a function to run in a specific amount of `uranium.update` calls/ticks.
Schedules a function to run in a specific amount of `update` calls/ticks.
#### `scheduler.unschedule(i: index): void`
@ -892,13 +973,13 @@ local counter = {
savedata.s(counter)
function uranium.init()
uranium.on('init', function()
print(counter.n) --> could be different from 0!
end
end)
function uranium.update()
uranium.on('update', function()
counter.n = counter.n + 1 -- this will be saved the next time savedata.save is called
end
end)
```
By default, the name that's used for your module will be the folder your Lua file is located in, followed by its filename. **This means you should not rely on the automatic name generation if your Lua file rests at the root of your file or if you're calling this function via `loadstring` or similar** as it will create unpredictable module names that will change between setups and sometimes even game restarts. You can pass in any string you like to `name`, as long as it's unique in your project, to override this behavior.
@ -909,7 +990,7 @@ Saves the savedata onto the user's profile. It waits a single tick to do so and
#### `savedata.load(): void`
Loads the savedata. _Shouldn't be called manually; this is automatically called on [`uranium.init()`](#uraniuminit)._
Loads the savedata. _Shouldn't be called manually; this is automatically called on [`init()`](#init)._
#### `savedata.getLastSave(): string[] | nil`
@ -917,7 +998,7 @@ Gets the last save time that persists between game restarts in the format `{hour
#### `savedata.enableAutosave(): void`
Enables autosave via [`uranium.exit()`](#uraniumexit). Should hopefully mean data should never get lost.
Enables autosave via [`exit()`](#exit). Should hopefully mean data should never get lost.
### `env`
@ -986,6 +1067,24 @@ _Exports globals_
A direct copy of [Mirin Template's `ease.lua`](https://github.com/XeroOl/notitg-mirin/blob/master/template/ease.lua), for convinience. See the docs for those [**here**](https://xerool.github.io/notitg-mirin/docs/eases.html).
### `players`
_Exports globals_
Pulls in the players as `P[1-8]` and `P<1-8>`.
```lua
require('stdlib.players')
P1:hidden(1)
P2:hidden(1)
```
### `profiler`
_Defines callbacks_
A simple profiler for Uranium Template's callback system. Require it and it'll display in the left-top corner of your screen, showing what callback functions are taking the longest to run.
### `util`
_Exports globals_
@ -996,25 +1095,18 @@ There's _a bit too many_ functions to document, so I'd recommend just looking th
### `aft`
An AFT setup library. Sets up sprites and AFTs with `sprite` and `aft`, respectively, making them ready for texturing use.
An AFT setup library. Sets up sprites and AFTs with `sprite` and `aft`, or all-in-one with `aftSetup`, making them ready for texturing use.
```lua
local aftSetup = require('stdlib.aft')
local aftlib = require('stdlib.aft')
local aft = ActorFrameTexture()
local aftSprite = Sprite()
aftSetup.sprite(aftSprite)
aft:addcommand('Init', function(self)
aftSetup.aft(aft) -- put this here; else it'll recreate it every frame!
aftSprite:SetTexture(self:GetTexture())
end)
-- aftSprite is a Sprite, set to the texture of aft, an ActorFrameTexture
local aft, aftSprite = aftlib.aftSetup()
```
### `noautplay`
### `noautoplay`
A single function which can be called before `uranium.ready()` to disable autoplay for the duration of the file if the player has it on. ***Not tested.***
A single function which can be called before `ready()` to disable autoplay for the duration of the file if the player has it on. ***Not tested.***
```lua
require('stdlib.noautoplay')()
@ -1022,7 +1114,7 @@ require('stdlib.noautoplay')()
### `eternalfile`
A single function which turns your file into an eternal, neverending file, until the player puts it out of its misery by exiting. The current beat will always go from 0 to 1 and start over once this is enabled.
A single function which turns your file into an eternal, neverending file, until the player puts it out of its misery by exiting. The current beat will always go from 0 to 1 and start over once this is enabled. This also sets the notedata to nothing to avoid hitting padding mines.
```lua
require('stdlib.eternalfile')()
@ -1046,14 +1138,18 @@ Here are a couple of examples. All of these are standalone `main.lua` files that
local text = BitmapText('common', 'Hello, world!')
text:xy(scx, scy)
function uranium.update()
uranium.on('update', function()
text:Draw()
end
end)
```
### Default Uranium Template code
```lua
require('stdlib.color')
require('stdlib.players')
P1:hidden(1)
P2:hidden(2)
require('stdlib.eternalfile')()
-- define a basic quad
local quad = Quad()
@ -1061,6 +1157,7 @@ quad:xy(scx, scy)
quad:zoom(120)
quad:diffuse(0.8, 1, 0.7, 1)
quad:skewx(0.2)
uranium.config.resetActorOnFrameStart(quad)
-- define a sprite
local sprite = Sprite('docs/uranium.png')
@ -1074,7 +1171,7 @@ text:xy(scx, scy + 100)
-- update gets called every frame
-- dt here refers to deltatime - the time that has passed since the last frame!
function uranium.update(dt)
uranium.on('update', function(dt)
-- let's rotate our quad
quad:rotationz(t * 80)
-- then shove it to the screen - similar to a drawfunction!
@ -1102,7 +1199,7 @@ function uranium.update(dt)
-- wag the text
text:rotationz(math.sin(t * 2) * 10)
text:Draw()
end
end)
```
### Simple platformer base
@ -1134,15 +1231,15 @@ local vel = vector(0, 0)
local hasHitGround = true -- let's define this so that you can't jump mid-air
-- called whenever the player recieves an input
function uranium.press(i)
uranium.on('press', function(i)
if i == input.inputType.Up and hasHitGround then
vel.y = vel.y - JUMP_FORCE
hasHitGround = false
return true -- input eaten! further callbacks won't recieve this
end
end
end)
function uranium.update(dt)
uranium.on('update', function(dt)
-- respond to l/r inputs
if input.isDown('Left') then
vel.x = vel.x - SPEED
@ -1178,7 +1275,7 @@ function uranium.update(dt)
-- draw the ground
ground:Draw()
end
end)
```
### AFTs
@ -1213,7 +1310,7 @@ end)
local text = BitmapText('common', 'uranium template!')
text:xy(scx, scy)
function uranium.update(dt)
uranium.on('update', function(dt)
coverQuad:Draw()
aftSprite:Draw()
@ -1228,7 +1325,7 @@ function uranium.update(dt)
aft:Draw()
text:Draw()
end
end)
```
### Shader test
@ -1290,14 +1387,12 @@ void main() {
gl_FragColor = col * color;
}
]])
shader:uniform1f('yo', 1)
shader:uniform1f('scale', 0.25)
setShader(sprite, shader)
function uranium.init()
setShader(sprite, shader)
end
uranium.on('update', function()
shader:uniform1f('yo', 1)
shader:uniform1f('scale', 0.25)
function uranium.update()
shader:uniform1f('tx', t)
shader:uniform1f('ty', t)
@ -1308,7 +1403,7 @@ function uranium.update()
reset(sprite)
shader:uniform1f('yo', 0)
sprite:Draw()
end
end)
```
### Savedata example
@ -1329,7 +1424,7 @@ savedata.s(save)
local text = BitmapText('common', '')
text:xy(scx, scy)
function uranium.press(key)
uranium.on('press', function(key)
if key == input.inputType.Left then
save.leftPresses = save.leftPresses + 1
elseif key == input.inputType.Right then
@ -1337,9 +1432,9 @@ function uranium.press(key)
elseif key == input.inputType.Down then
savedata.save()
end
end
end)
function uranium.update(dt)
uranium.on('update', function(dt)
text:settext(
'left presses: ' .. save.leftPresses .. '\n' ..
'right presses: ' .. save.rightPresses
@ -1351,7 +1446,7 @@ function uranium.update(dt)
text:settext('saving!')
text:Draw()
end
end
end)
```
### Simple ActorFrame setup
@ -1404,9 +1499,9 @@ setDrawFunction(af, function()
sprite:Draw()
end)
function uranium.update()
uranium.on('update', function()
af:Draw()
end
end)
```
## Credits

View File

@ -28,18 +28,18 @@ Then define callbacks with a simple function definition:
```lua
local timer = 0
function uranium.update(dt)
uranium.on('update', function(dt)
timer = timer + dt
end
end)
```
And then define the draw order of your actors with simple method calls, similar to DrawFunctions:
```lua
function uranium.update()
uranium.on('update', function()
quad:rotationz(t * 50)
quad:Draw()
end
end)
```
It comes with an extensive standard library, including common game-development needs like:

View File

@ -1,2 +1,2 @@
#!/bin/bash
zip -9 -r package-template.zip --exclude="*.git/*" --exclude="*template/.git*" --exclude="*.gitignore_local*" --exclude="*.gitmodules*" --exclude="*.typings*" --exclude="*template/docs*" --exclude="*README.md" --exclude="*.sm.auto*" --exclude="*.sm.old*" --exclude="*distribute-template.sh*" .
zip -9 -r package-template.zip --exclude="*.git/*" --exclude="*template/.git*" --exclude="*.gitignore_local*" --exclude="*.gitmodules*" --exclude="*.typings*" --exclude="*template/docs*" --exclude="*README.md" --exclude="*.sm.auto*" --exclude="*.sm.old*" --exclude="*distribute-template.sh*" --exclude="*update-release.sh*" --exclude="*release.blank.lua*" .

View File

@ -1,4 +1,8 @@
require('stdlib.color')
require('stdlib.players')
P1:hidden(1)
P2:hidden(2)
require('stdlib.eternalfile')()
-- define a basic quad
local quad = Quad()
@ -6,6 +10,7 @@ quad:xy(scx, scy)
quad:zoom(120)
quad:diffuse(0.8, 1, 0.7, 1)
quad:skewx(0.2)
uranium.config.resetActorOnFrameStart(quad)
-- define a sprite
local sprite = Sprite('docs/uranium.png')
@ -19,7 +24,7 @@ text:xy(scx, scy + 100)
-- update gets called every frame
-- dt here refers to deltatime - the time that has passed since the last frame!
function uranium.update(dt)
uranium.on('update', function(dt)
-- let's rotate our quad
quad:rotationz(t * 80)
-- then shove it to the screen - similar to a drawfunction!
@ -47,4 +52,4 @@ function uranium.update(dt)
-- wag the text
text:rotationz(math.sin(t * 2) * 10)
text:Draw()
end
end)

@ -1 +1 @@
Subproject commit 4e8ba205621df4df01643dc6eea181656fc23bf8
Subproject commit 912bb8f234023e9020e9091b85a4e096b0ecea43

4
update-release.sh Executable file
View File

@ -0,0 +1,4 @@
#!/bin/bash
rm template/uranium/release.lua
read -p "enter release version: " version
sed -e "s/branch = 'unknown'/branch = '$(git rev-parse --abbrev-ref HEAD)'/" -e "s/commit = 'unknown'/commit = '$(git rev-parse --short HEAD)'/" -e "s/version = 'unknown'/version = '$version'/" template/uranium/release_blank.lua > template/uranium/release.lua