Merge pull request #81 from santiaboy/scene-args

Add an optional table argument which is passed to scene's init

Noble.lua

@@ -77,6 +77,7 @@ local configuration = Utilities.copy(defaultConfiguration)
 -- @tparam[opt=Noble.Transition.DipToBlack] Noble.Transition __launcherTransition If a transition duration is set, use this transition type.
 -- @tparam[opt={}] table __launcherTransitionProperties Provide a table of properties to apply to the launcher transition. See the documentation for the transition you're using for a list of available properties.
 -- @tparam[opt={}] table __configuration Provide a table of Noble Engine configuration values. This will run `Noble.setConfig` for you at launch.
+-- @tparam[opt={}] table __sceneProperties A table consisting of user-defined properties which are passed into and handled by the new scene's init() method.
 -- @usage
 -- Noble.new(
 -- 	TitleScreen,
@@ -95,7 +96,8 @@ local configuration = Utilities.copy(defaultConfiguration)
 -- @see NobleScene
 -- @see Noble.Transition
 -- @see setConfig
-function Noble.new(StartingScene, __launcherTransitionDuration, __launcherTransition, __launcherTransitionProperties, __configuration)
+-- @see NobleScene.init
+function Noble.new(StartingScene, __launcherTransitionDuration, __launcherTransition, __launcherTransitionProperties, __configuration, __sceneProperties)
 
 	math.randomseed(playdate.getSecondsSinceEpoch()) -- Set a new random seed at runtime.
 
@@ -131,10 +133,11 @@ function Noble.new(StartingScene, __launcherTransitionDuration, __launcherTransi
 	local launcherTransition =			__launcherTransition or defaultConfiguration.defaultTransition
 	local launcherTransitionDuration =	__launcherTransitionDuration or 1.5
 	local launcherTransitionProperties =__launcherTransitionProperties or {}
+	local sceneProperties = __sceneProperties or {}
 
 	-- Now that everything is set, let's-a go!
 	engineInitialized = true
-	Noble.transition(StartingScene, launcherTransitionDuration, launcherTransition, launcherTransitionProperties)
+	Noble.transition(StartingScene, launcherTransitionDuration, launcherTransition, launcherTransitionProperties, sceneProperties)
 end
 
 --- This checks to see if `Noble.new` has been run. It is used internally to ward off bonks.
@@ -209,27 +212,38 @@ local queuedScene = nil
 -- @number[opt=1.5] __duration The length of the transition, in seconds.
 -- @tparam[opt=Noble.TransitionType.DIP_TO_BLACK] Noble.Transition __transition If a transition duration is set, use this transition type. If not set, it will use the value of `configuration.defaultTransition`.
 -- @tparam[opt={}] table __transitionProperties A table consisting of properties for this transition. Properties not set here will use values that transition's `defaultProperties` table.
+-- @tparam[opt={}] table __sceneProperties A table consisting of user-defined properties which are passed into and handled by the new scene's init() method.
 -- @usage
--- Noble.transition(Level2, 1, Noble.Transition.CrossDissolve, {
--- 	dither = Graphics.image.kDitherTypeDiagonalLine
--- 	ease = Ease.outQuint
--- })
+-- Noble.transition(Level2, 1, Noble.Transition.CrossDissolve,
+-- 	{
+-- 		dither = Graphics.image.kDitherTypeDiagonalLine
+-- 		ease = Ease.outQuint
+-- 	}
+-- )
 -- --
--- Noble.transition(Level2, 1, Noble.Transition.DipToBlack, {
--- 	holdTime = 0.5,
--- 	ease = Ease.outInElastic
--- })
+-- Noble.transition(Level2, 1, Noble.Transition.DipToBlack,
+-- 	{
+-- 		holdTime = 0.5,
+-- 		ease = Ease.outInElastic
+-- 	}
+-- )
 -- --
--- Noble.transition(Level2, 1, Noble.Transition.SlideOff, {
--- 	x = 400,
--- 	y = 150
--- 	rotation = 45
--- })
+-- Noble.transition(Level, 1, Noble.Transition.SlideOff,
+-- 	{
+-- 		x = 400,
+-- 		y = 150
+-- 		rotation = 45
+-- 	},
+-- 	{
+-- 		levelName = "Level Two: The Second Level!"
+-- 		levelData = "levels/level2.json",
+-- 	}
+-- )
 -- @see Noble.isTransitioning
 -- @see NobleScene
 -- @see Noble.Transition
 -- @see Noble.Transition.defaultProperties
-function Noble.transition(NewScene, __duration, __transition, __transitionProperties)
+function Noble.transition(NewScene, __duration, __transition, __transitionProperties, __sceneProperties)
 	if (isTransitioning) then
 		-- This bonk no longer throws an error (compared to previous versions of Noble Engine), but maybe it still should?
 		warn("BONK: You can't start a transition in the middle of another transition, silly!")
@@ -240,7 +254,7 @@ function Noble.transition(NewScene, __duration, __transition, __transitionProper
 		-- We don't return here because maybe the developer *did* intend to override a previous call to Noble.transition().
 	end
 
-	queuedScene = NewScene()	-- Creates new scene object. Its init() function runs now.
+	queuedScene = NewScene(__sceneProperties) -- Creates new scene object. Its init() function runs now.
 
 	currentTransition = (__transition or configuration.defaultTransition)(
 		__duration or configuration.defaultTransitionDuration,

modules/NobleScene.lua

@@ -113,7 +113,7 @@ end
 --		--[Your code here]--
 --	end
 --
-function NobleScene:init()
+function NobleScene:init(__sceneProperties)
 	self.name = self.className
 	self.sprites = {}
 end

templates/SceneTemplate.lua

@@ -2,12 +2,12 @@
 -- SceneTemplate.lua
 --
 -- Use this as a starting point for your game's scenes.
--- Copy this file to your root "scenes" directory,
--- and rename it.
+-- Copy this file into your project's "scenes" directory,
+-- and then rename it.
 --
 
 -- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
--- !!! Rename "SceneTemplate" to your scene's name in these first three lines. !!!
+-- !!! Rename 'SceneTemplate' to your scene's name in these first three lines. !!!
 -- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 SceneTemplate = {}
@@ -18,37 +18,52 @@ local scene = SceneTemplate
 -- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 -- It is recommended that you declare, but don't yet define,
--- your scene-specific varibles and methods here. Use "local" where possible.
+-- your scene-specific variables and methods here. Use "local" where possible.
+--
+-- Examples:
+--
+-- local variable1 = nil
+-- "Private" variable. It can only be accessed within this file.
+--
+-- scene.variable2 = nil
+-- "Public" variable.
+-- When accessed outside this file, call it using `SceneTemplate.variable2`.
+-- When accessed inside a method in this file, you may also use `self.variable2`.
 --
--- local variable1 = nil	-- local variable
--- scene.variable2 = nil	-- Scene variable.
---							   When accessed outside this file use `SceneTemplate.variable2`.
--- ...
 --
 
 -- This is the background color of this scene.
 scene.backgroundColor = Graphics.kColorWhite
 
 -- This runs when your scene's object is created, which is the
--- first thing that happens when transitining away from another scene.
-function scene:init()
+-- first thing that happens when transitioning away from another scene.
+-- Properties passed into this scene via `Noble.transition` or `Noble.new`
+-- should be handled here.
+function scene:init(__sceneProperties)
 	scene.super.init(self)
 
-	-- variable1 = 100
-	-- SceneTemplate.variable2 = "string"
+	-- Your code here, e.g.:
+
+	-- Global.thing = 100
+	-- variable1 = "some text"
+	-- self.variable2 = __sceneProperties.variable2
 	-- ...
 
-	-- Your code here
 end
 
 -- When transitioning from another scene, this runs as soon as this
 -- scene needs to be visible (this moment depends on which transition type is used).
+-- This is also the point where this scene becomes the 'currentScene' according to
+-- Noble Engine, and its update loop will begin executing on every frame.
 function scene:enter()
 	scene.super.enter(self)
 	-- Your code here
 end
 
 -- This runs once a transition from another scene is complete.
+-- This scene's input handler will be enabled at this point and
+-- The player will be able to interact with the scene.
+-- Use this method to begin this scene's game logic.
 function scene:start()
 	scene.super.start(self)
 	-- Your code here
@@ -87,7 +102,7 @@ function scene:resume()
 	-- Your code here
 end
 
--- Define the inputHander for this scene here, or use a previously defined inputHandler.
+-- Define the inputHandler for this scene here, or use a previously defined inputHandler.
 
 -- scene.inputHandler = someOtherInputHandler
 -- OR