Documentation lives in /libraries/noble so it gets bundled in the pdx

Adds ~220KB to pdx file size, and slows build time

I would definitely appreciate knowing more about when and where to use some of them! (Also definitely appreciate the documentation in the rest of the project more generally.)

Describe the bug
When building the game using the VSCode Playdate Template, the game builds successfully, but fails to load with a "pdxinfo file not found" error, even though the pdxinfo file is present in the correct directory ("source" folder).

To reproduce
Combine NobleEngine template project with https://github.com/Whitebrim/VSCode-PlaydateTemplate .
Use the Run build task... function in VSCode to build a pdx file and run it in the simulator.

Expected behavior
The pdxinfo file is present in the source folder.
The game should boot normally without any errors in the simulator.

Screenshots/Code snippets

Describe the feature
Noble.handoff(...) to add to the stack, and a Noble.return() to pop it.

Describe alternatives you've considered
Noble.transition(...) could push every time, then return would be automatic. But that would add a ton of overhead compared to the current system since it wouldn't be a blind upgrade. A "scene_stack_size" setting defaulted to 0 might help.

Alternately, a Noble.swap(...) that has a return function and it only ever goes 1 deep.

What problems would this solve or help prevent, if any

This would be useful for inventory screens, hub worlds, areas with lots of enterable buildings.

This might require a NobleScene:reenter callback too, a noop

Additional context

[This area intentionally left blank]

Hi @NobleRobot -- I'm usually inclined to submit a PR to address bugs, but I'm unsure of how best to handle this one.

I've created a menu and set it to use localization keys, rather than strings, for item names.

mainMenu = Noble.Menu.new(
		false,
		Noble.Text.ALIGN_CENTER,
		true,
		Graphics.kColorBlack,
		4,
		6,
		0
	)

I also add a couple menu items:

mainMenu:addItem(
		"mainMenuPlay",
		function()
			print("INFO: mainMenu Play")
		end,
		nil,
		nil,
		true
	)
	
	mainMenu:addItem(
		"mainMenuOptions",
		function()
			print("INFO: mainMenu Options")
		end
	)

However, this results in warnings logged to the console: Localized text not found for the key: Play

Digging into the source I've discovered the source of these warnings. In the Menu module, the method getDisplayName (Around line 417) returns the proper localized string if self.localized is true. It then returns that string.

That method is called as part of drawItem and drawSelectedItem. However, the returned string (which is the localized string and not the localization key), is then re-localized as part of the Noble.Text.draw call, if self.localized is true.

(Please do let me know if I'm being unclear here and I'll happily share more.)

As I said, I like to contribute where I can with PRs but I'm unsure of your intention here or if there's anything I'm missing. Happy to contribute code changes, if you have guidance. Thanks!

Describe the bug
I can't get a NobleSprite to display an animation from a table.

Screenshots/Code snippets
This is my class.

BigExplosion = {}
class("BigExplosion").extends(NobleSprite)

local prefix <const> = "[BigExplosion] "

function BigExplosion:init(__x, __y)
    BigExplosion.super.init(self, "assets/images/big-explosion", true, true, false)

    self:add(__x, __y)
end

function BigExplosion:update()
    BigExplosion.super.update(self)
    
    print(prefix .. "Current frame: " .. self.animation.currentFrame)
end

Additional context
Other NobleSprites without an animation work fine.

From the update function print, currentFrame stays at 1, but I also don't see the first frame on the screen. Position seems fine and the scene appears to contain the sprite correctly.

update failed: lib/noble/modules/Noble.Input.lua:190: attempt to index a nil value (upvalue 'currentHandler')
stack traceback:
	lib/noble/modules/Noble.Input.lua:190: in function <lib/noble/modules/Noble.Input.lua:189>

This seems to be because currentHandler is nil even though my scene does have an event handler

It's what all the cool kids are doing.

Typo Inside Noble.Input.lua causes crankDocked behavior to run when calling crankUndocked.
Similar typo in documentation, inside examples/scenetemplate.lua.html

Describe the feature

I love Noble Engine's scene transitions, and it would be fantastic to be able to define custom ones.

For example: having the game's own character walk across the screen as a wipe.

Describe alternatives you've considered

I'm not sure how else this could be achieved in a way that doesn't feel hacky.

Hello, thank you for your clean scene oriented engine.

I was using gfx.sprite.setBackgroundDrawingCallback in my previous version code. During the port of my game with NobleEngine, i saw NobleScene:drawBackground have not access to arguments x, y, width, height given by playdate engine setBackgroundDrawingCallback. And I need it for performance optimisation (I do not need to redraw the entire screen each update).

So in Noble.lua (in my local copy of the code) I replaced

	Graphics.sprite.setBackgroundDrawingCallback(
		function ()
			if (currentScene ~= nil) then
				 -- Each scene has its own method for this. We only want to run one at a time.
				currentScene:drawBackground()
			end
		end
	)

by

	Graphics.sprite.setBackgroundDrawingCallback(
		function (x, y, width, height)
			if (currentScene ~= nil) then
				 -- Each scene has its own method for this. We only want to run one at a time.
				currentScene:drawBackground(x, y, width, height)
			end
		end
	)

And in NobleScene.lua

function NobleScene:drawBackground()
	Graphics.clear(self.backgroundColor)
end

function NobleScene:drawBackground(x, y, width, height)
	local color <const> = Graphics.getColor()

	Graphics.setColor(self.backgroundColor)
	Graphics.fillRect(x, y, width, height)

	Graphics.setColor(color)
end

It could be great to integrate this in this repository

Describe the bug
When an animated sprite is drawn in the negative bounds (either x or y), the image will get rendered incorrectly. The image will slide such that the left most part of the frame is drawn starting from the x or y 0 coordinate rather than off the screen.

To reproduce

1. Create an animated sprite
2. Move it to a coordinate where x or y is negative either with add or moveTo
3. Observe that the sprite is rendered incorrectly

Expected behavior
I expect to see the correct half of the sprite drawn on the screen.

Screenshots/Code snippets
In the code below, I draw an animated sprite and a static sprite that are somewhat offscreen. Notice how the animated sprite slides over, whereas the static one draws as expected.

local animSprite= NobleSprite("assets/images/bwird_cabbage", true, true)
animSprite:setSize(80, 60)
animSprite:setCenter(0, 0)
animSprite:add(-20, 50)

local staticSprite = NobleSprite("assets/images/bwird.png")
staticSprite:setCenter(0, 0)
staticSprite:add(-20, 120)

Assets used:

Additional context

• Drawing the sprite offscreen on the right or bottom edge renders correctly.
• Passing the coordinates in moveTo vs add doesn't make a difference

Describe the bug
I tried to create a self drawing sprite with following code.

BallSprite.lua

BallSprite = {}
class("BallSprite").extends(NobleSprite)

function BallSprite:init(x, y)
    BallSprite.super.init(self)

    BallSprite:setSize(16, 16)
    BallSprite:setCollideRect(0, 0, 16, 16)

    self.direction = Geometry.vector2D.new(1, 1)
    self.speed = 8

    self:add(x, y)
end

function BallSprite:draw(x, y, width, height)
    Graphics.fillCircleInRect(x, y, width, height)
end

function BallSprite:collisionResponse(other)
    return Graphics.sprite.kCollisionTypeBounce
end

LevelScene.lua

import("entities/ball")

LevelScene = {}
class("LevelScene").extends(NobleScene)
local scene = LevelScene

function scene:init()
    scene.super.init(self)

    BallSprite(100, 100)
end

function scene:enter()
    scene.super.enter(self)
end

function scene:start()
    scene.super.start(self)
end

function scene:update()
    scene.super.update(self)
end

function scene:exit()
    scene.super.exit(self)
end

function scene:finish()
    scene.super.finish(self)
end

The error message is

entities/ball.lua:7: bad argument #-2 to 'setSize' (playdate.graphics.spriteud expected, got nil)
stack traceback:
	[C]: in method 'setSize'
	entities/ball.lua:7: in field 'init'
	CoreLibs/object.lua:70: in global 'BallSprite'
	scenes/Level.lua:10: in field 'init'
	CoreLibs/object.lua:70: in field 'NewScene'
	libraries/noble/Noble.lua:268: in upvalue 'executeTransition'
	libraries/noble/Noble.lua:459: in function <libraries/noble/Noble.lua:425>

What am I doing wrong here?

Describe the feature
It would be nice if I could set a function's debug draw function similar to scene:drawBackground. The color could also be set like scene.debugColor, (and then pd.setDebugDrawColor(r, g, b, a)) so it's like background.

Describe alternatives you've considered
I could add it my own, and rn I'm going to do it by manually adding it in my scene:enter and scene:exit for my base scene

What problems would this solve or help prevent, if any
It would be cool, and I'm adding a debug system menu toggle that I want to use. Having a

Additional context
Here's what I'm currently doing in my BaseScene.lua:

BaseScene.debugColor = {1, 0, 0, 0.5}

function BaseScene:enter()
    BaseScene.super.enter(self)

    pd.setDebugDrawColor(table.unpack(self.debugColor))
    function playdate.debugDraw()
        self:drawDebug()
    end
end

function BaseScene:exit()
    BaseScene.super.exit(self)
    
    function playdate.debugDraw() end
end

function BaseScene:drawDebug() end

Chance to get crash while transitioning between scenes, if scene transition type = Noble.Transition.Type.COVER.

Update error: libraries/noble/Noble.lua:269: attempt to index a nil value (upvalue 'currentScene')
stack traceback:
    libraries/noble/Noble.lua:269: in field 'transitionMidpointHandler'
    libraries/noble/modules/Noble.Transition.lua:115: in field 'fn'
    libraries/noble/libraries/Sequence.lua:359: in local 'callTimeRange'
    libraries/noble/libraries/Sequence.lua:368: in method 'updateCallbacks'
    libraries/noble/libraries/Sequence.lua:81: in field 'update'
    libraries/noble/Noble.lua:311: in function <libraries/noble/Noble.lua:308>

To increase chance of crash set duration of transition about 2 * frame duration. It can be 0.060 or 0.062 or 0.064 or 0.066 (if your FPS = 30).

Noble.transition(ExampleScene2, 0.062, Noble.Transition.DipToBlack)

The reason for the crash is that sometimes you can get two midpoint callbacks in one Sequence. I described that here: NicMagnier/PlaydateSequence#10

Pull request with the fix: #66

Just started playing around with Noble and it's really slick!

Describe the bug
When activating a menu, no selection is made.

Expected behavior
Based on the Menu:activate() docstring:

	--- Activate this menu.
	-- This selects the most recently selected menu item (or the first item if none have been previously selected), and enables this menu's @{selectPrevious|selectPrevious}, @{selectNext|selectNext}, and @{click|click} methods.
	-- @usage
	--	local menu = Noble.Menu.new(false)
	--	menu:activate()

I would expect activate() to select "the first item if none have been previously selected".

To reproduce
Clone the NobleEngine-ProjectTemplate and run it in the Playdate simulator.

Screenshots/Code snippets
Upon launch of the noble project template pdx, observe that there is no menu selection:

After dPadDown (menu:selectNext()), observe that the menu's Index 1 option is selected:

If dPadUp (menu:selectPrevious()) is inputted, the menu appears to traverse "invisible" negative indices and you will have to selectNext() an equal number of times to get "back" into the menu.

Additional comments
This looks like a simple fix related to the order of the select() call and active = true in activate().

Changing Scene.baseColor doesn't do anything, I've checked code and baseColor is not readed anywhere.

Hi! The Japanese characters in NobleSans currently have some issues that I think amount to deal-breakers in using it for that language (at least, for me personally they do).

Tsu and shi confusion. The biggest issue is probably that your ツ (tsu) looks too much like a シ (shi). I know that this is a common general complaint about those two characters; but in this case I think a native Japanese person would read your ツ as a シ, and be fairly confused if they found it being used as a "tsu". The main issue with it is that the right small mark appears substantially above the left one, and both marks are too diagonal. If you look at the actual character ツ here (regardless of what font you're seeing it with), those two marks should be very nearly even, horizontally, not arranged diagonally. In a small font like this, they should be exactly on the same vertical level (the same horizontal line). They also needn't be angled—it would be better to have the marks straight up and down than for them to have their current steep diagonal.

(The same issue with ツ appears with ヅ, and to a lesser extent the small ッ (but that one is saved by virtue of the fact that you don't really encounter a small シ (shi) character... I apparently can't even type one).

Dakuten inconsistency. The other issue I notice is that for the various characters that have the dakuten ゛marks, their form is inconsistent, and often confusable with the handakuten ゜marks. To be sure, your handakuten is clearly distinguishable from your dakuten; but if (as can easily happen) a string of Japanese text one only sees the dakuten, the one on ボ, ぼ, and ぶ could easily be taken for ポ, ぽ, or ぷ, since they appear to form a ball rather than two distinct marks. There are many other characters where the dakuten looks like they could be handakuten, but most of the other characters are ones that don't take handakuten, so it probably matters less for them. I suspect the ヷ (Apparently a rare old form of ヴァ "va") could be taken as プ ("pu"), but since no one's going to use that it doesn't really matter.

But, quite a few of your dakuten marks are clearly identifiable as dakuten marks, appearing as two clearly distinct strokes - the ones where both marks are vertically level (on the same horizontal line). For example, in your バビブベ. It's the ones where the left mark is slid further right-and-down, that they appear to form a small circle.

Anyway, I hope that helps. Thanks for making such a useful-looking engine for the PlayDate, and especially for releasing the source code publicly!

I'm having strange behaviour when it's gameover and scene transition from game scene to main menu scene, very rare MainMenu:enter() is called twice and it breaks scene initialization.

Documentation says:

When attached to a NobleSprite, this is called by NobleScene:draw() when added to a scene. For non-NobleSprite sprites, put this method inside your sprite's draw() method, or inside NobleScene:update.

Doesn't seem to be true for me unfortunately.

I'm actually curious where NobleScene:draw() is supposed to be because I haven't found it.

Typo in 432 line in libraries/Sequence.lua

local indexInRunningTable = table.indexOfElement(self)

Correct version:
local indexInRunningTable = table.indexOfElement(_runningSequences, self)

Due to a typo, the stop and pause functions did not work.

Describe the feature

Instead of using positional arguments for both required and optional parameters, I suggest that we use positional arguments for required parameters and a list at the end for optional parameters, e.g. :

-- from this
Noble.Text.draw(string, x, y, alignment, localized, font)
-- to this
Noble.Text.draw(string, x, y, options)

Of course since this kind of method signature is much more opaque, good documentation is mandatory to be able to know which options keys are available, but IMO this project's great docs make this a non-issue.

Also, eventhough the signature is more ambiguous, reading function calls is actually easier : animation:setState(self.animation.walk, true, self.animation.turn) vs.
animation:setState(self.animation.walk, self.animation.turn, { continuous = true })

What problems would this solve or help prevent, if any

This would allow us to supply a value to an optional parameter without having to give one to all of the optional arguments before that we don't care about.

Let's say I'm fine with the default left alignment and unlocalized text, if I want to change the font I currently still have to do this:

Noble.Text.draw("my text", x, y, Noble.Text.ALIGN_LEFT, false, Noble.Text.FONT_LARGE)

Whereas with the proposed change I could do this:

Noble.Text.draw("my text", x, y, { font = Noble.Text.FONT_LARGE })

Additionally this enables the following

• A set of options could be saved to a local variable and then reused easily (e.g. Noble.Text.draw("text", x, y, myConfig))
• This enables us to add more parameters to functions (e.g. set the text color directly in the draw function) without having to worry about a function having way too many parameters
• It can wrap lines a little more gracefully in the case of many arguments

Noble.Text.draw(
  "This is my text which is a little bit longer than usual and makes this a very long line",
  0,
  0,
  Noble.Text.ALIGN_CENTER, true, Noble.Text.FONT_LARGE
)

Noble.Text.draw("This is my text which is a little bit longer than usual and makes this a very long line", 0, 0, {
  alignment = Noble.Text.ALIGN_CENTER,
  localized = true,
  font = Noble.Text.FONT_LARGE
}

Additional context

This is also a convention that has been widely adopted in the JavaScript and TypeScript ecosystems

With fixes being rolled out, documentation being updated and features being added it would probably be a good idea to have explicit version numbers and releases in order to communicate changes with users. Currently there has been no breaking change but it might come up in the future and will be really needed then.

This also begs the question of "What version is NobleEngine currently at?" and if not 1.0, what needs to be done to bring it to 1.0.

Here is a unordered list of things that I think could be good additions to NobleEngine (in no special orders) that we could pick and choose from:

• Define a config object that can be passed in Noble.new and Noble.config to customise the behaviour of the engine (as mentioned in #36

• Allow specifying font variant directly in Noble.Text.draw (Inside Playdate - Variants)

• Allow specifying draw mode directly in Noble.Text.draw (e.g. by default text can be drawn in NXOR so that if you write on black pixels it will by default be white) (Inside Playdate - Drawing mode)

• Add a headphoneChanged custom event to inputHandler, and a config for Noble to automatically redirect audio output when this event is triggered (Inside Playdate - Audio Output)

• Add better primitives for working with the microphone, potentially custom events (config a custom sound level threshold and trigger an event when the mic detects it) (Inside Playdate - Mic Input)

• Provide a custom threshold to determine when a button is held (currently hardcoded at 3 frames)

• Add event handlers for charging / battery status (Inside Playdate - Power)

• Add event handlers to game lifecycle's callbacks, so that each scene can easily register different actions to perform (Inside Playdate - Game Lifecycle)

• Some optimization / performance pass on the entire codebase to minimize the performance overhead of the engine even further (Lua Performance Tips, Lua Optimisation Tips, Increase the performance of a Lua program)

• Have some sort of an established benchmark / test suite, to test for performance improvements/regression (on hardware)

• If we choose to go with #35 (which I advocate for of course 😋), it's going to be a pretty big breaking change, so the earlier the better?

Stuff that could be good but should probably be external tools / released independently

• An adapter to have Panels integrate nicely with NobleEngine now that it can be used as a library for cutscenes (https://github.com/cadin/panels/releases/tag/v1.1)
• Since text rendering performance is known to be pretty bad, a module for Noble.Text to support rendering text as sprites and have the lazy re-rendering done automatically
• A CLI to scaffold project, keep the engine and the SDK up-to-date, add scenes from a set of templates, build, run and transfer to playdate

I think I underestimated how fiddly git submodules are for people who haven't used them before, or rather, I didn't explain them well enough. I should add more thorough instructions to the README file, including workflows for both command line and GUI clients.

See: https://discord.com/channels/675983554655551509/980931046545690705/1008522731479904357

Describe the feature
Someone on the discord discovered a catalog game that had an exit animation and implemented it in their own game:

They don't use Noble, but they shared their code and it was surprisingly simple. I think it would be nice to easily support it on a per-scene basis. The other use for the function is to save data when the device does the thing.

Describe alternatives you've considered
You could do it manually, which is what I'm doing now.

What problems would this solve or help prevent, if any
It would show off the lesser-known parts of the SDK and easier saving when not using autosave on a per-scene basis

Additional context
Here's my case scene:

class("BaseScene").extends(NobleScene)

function BaseScene:enter()
    BaseScene.super.enter(self)

    function pd.gameWillTerminate() self:terminate() end
    function pd.deviceWillSleep() self:sleep() end
    function pd.deviceWillLock() self:lock() end
    function pd.deviceDidUnlock() self:unlock() end
end

function BaseScene:exit()
    BaseScene.super.exit(self)

    function pd.gameWillTerminate() end
    function pd.deviceWillSleep() end
    function pd.deviceWillLock() end
    function pd.deviceDidUnlock() end
end

function BaseScene:terminate() end
function BaseScene:sleep() end
function BaseScene:lock() end
function BaseScene:unlock() end

I'm seeing this in the simulator when running a new instance of the template project.

Typo Inside Noble.Animation.lua causes __endFrame to be the first frame in the imagetable:

-- @int __endFrame This is the first frame for this animation in the imagetable/spritesheet

A while ago I sent you a test app and you looked at it for a while before figuring out what I was doing wrong, or what I had assumed incorrectly. I forget!

Anyway, I think there was an issue that needed resolving with that, but I never filed it.

Does this make sense?

Steps:

1. Open the Noble example project
2. comment out the Difficulty line in Settings.Setup
3. build & run it
4. the game will crash
5. Notice your settings.json file contains just []
6. uncomment the Difficulty line
7. build & run

The game still crashes. It looks like changing settings to contain {} fixes the problem and avoids the "new key" issue I mentioned on discord.

update failed: lib/noble/modules/Noble.Input.lua:190: attempt to index a nil value (upvalue 'currentHandler')
stack traceback:
	lib/noble/modules/Noble.Input.lua:190: in function <lib/noble/modules/Noble.Input.lua:189>

This seems to be because currentHandler is nil even though my scene does have an event handler

In the base SDK a previously loaded image can be used to create a sprite. This means it wouldn't need loading in each time and would allow easier porting from the base sdk to NobleEngine.