Core.yield: Difference between revisions

From GiderosMobile
No edit summary
No edit summary
Line 89: Line 89:
*Sequential execution: The for loop looks like traditional synchronous code, but Core.yield(1) cleanly injects a delay between each iteration.
*Sequential execution: The for loop looks like traditional synchronous code, but Core.yield(1) cleanly injects a delay between each iteration.
*No game freezing: While this timer is counting down, your players can still touch buttons, sprites can animate, and physics will continue to update normally.
*No game freezing: While this timer is counting down, your players can still touch buttons, sprites can animate, and physics will continue to update normally.
'''Core.yield(true)'''
<syntaxhighlight lang="lua">
-- Assume 'mySprite' is an existing image or shape on the stage
local mySprite = Bitmap.new(Texture.new("character.png"))
stage:addChild(mySprite)
mySprite:setPosition(0, 200)
-- Launch the animation inside an async thread
Core.asyncCall(function()
    print("Animation Start")
    -- Move the sprite from X=0 to X=300
    while mySprite:getX() < 300 do
        local currentX = mySprite:getX()
        -- Move 2 pixels forward every single frame
        mySprite:setX(currentX + 2)
        -- Pause here and wait until the next game frame is drawn
        Core.yield(true)
    end
    print("Animation Complete! 🎉")
end)
</syntaxhighlight>
Why Use Core.yield(true) Over Event.ENTER_FRAME?
Traditionally, game loops use Event.ENTER_FRAME listeners. While event listeners are great, Core.yield(true) provides significant benefits for multi-step animations:
#Linear Logic: You can sequence actions naturally. For example, you can slide a character right, Core.yield(1) to pause for a second, and then fade them out using a Core.yield(true) loop—all within a single block of code
#Local Variables Retention: All your loop variables stay safely within the function scope. You don't have to pollute your global space with variables like isAnimating or targetX


=== See also ===
=== See also ===

Revision as of 09:51, 29 September 2026

Available since: Gideros 2016.06
Class: Core

Description

Yields the function running as background task.

Core.yield(state)

Core.yield([number of seconds to wait])

Core.yield(true) -- yield for a single frame and disable auto yield

Core.yield(false) -- don't yield now, but reenable autoyield

In Gideros, Core.yield(number) pauses the execution of the current asynchronous task or background thread for number seconds before resuming it. How it Works:

  • Time-based Delay: Passing a number like 1 tells the engine to suspend the running coroutine/async function (started via Core.asyncCall or Core.asyncThread) and wait for that many seconds to pass in real time
  • Non-blocking: While this specific task is paused, the main game loop and other engine processes continue running smoothly without freezing

Alternative Arguments:

  • Core.yield(true) pauses execution until the very next frame
  • Core.yield(number) pauses execution for the specified number of seconds

Parameters

state: (number or boolean) number of seconds to yield or boolean to enable/disable auto yield

Examples

local txt1_noads = TextField.new(nil, "no ads")
local txt2_plusincome = TextField.new(nil, "plus income")
local btn_OK = TextField.new(nil, "OK")
-- position
txt1_noads:setPosition(64, 64*1)
txt2_plusincome:setPosition(64, 64*3)
btn_OK:setPosition(64, 64*5)
-- scale
local FontScale = 4
local tempFontScale = 8
txt1_noads:setScale(FontScale)
txt2_plusincome:setScale(FontScale)
btn_OK:setScale(FontScale)
-- order
stage:addChild(txt1_noads)
stage:addChild(txt2_plusincome)
stage:addChild(btn_OK)

local function scaleTextsAndBtn()
	Core.yield(2)
	txt1_noads:setScale(tempFontScale)
	Core.yield(1)
	txt1_noads:setScale(FontScale)

	Core.yield(1)
	txt2_plusincome:setScale(tempFontScale)
	Core.yield(1)
	txt2_plusincome:setScale(FontScale)

	Core.yield(1)
	btn_OK:setScale(tempFontScale)
	Core.yield(0.5)
	btn_OK:setScale(FontScale)
end
 
Core.asyncCall(scaleTextsAndBtn)

A simple function that counts down from a given number

local function startCountdown(seconds)
    Core.asyncCall(function()
        print("Timer started!")
        
        for i = seconds, 1, -1 do
            print("Time remaining: " .. i .. " seconds")
            
            -- Pause this specific task for exactly 1 second
            Core.yield(1) 
        end
        
        print("Time's up! 🚀")
    end)
end

-- Start a 5-second countdown
startCountdown(5)

Key Takeaways from this Example

  • Sequential execution: The for loop looks like traditional synchronous code, but Core.yield(1) cleanly injects a delay between each iteration.
  • No game freezing: While this timer is counting down, your players can still touch buttons, sprites can animate, and physics will continue to update normally.

Core.yield(true)

-- Assume 'mySprite' is an existing image or shape on the stage
local mySprite = Bitmap.new(Texture.new("character.png"))
stage:addChild(mySprite)
mySprite:setPosition(0, 200)

-- Launch the animation inside an async thread
Core.asyncCall(function()
    print("Animation Start")

    -- Move the sprite from X=0 to X=300
    while mySprite:getX() < 300 do
        local currentX = mySprite:getX()

        -- Move 2 pixels forward every single frame
        mySprite:setX(currentX + 2)

        -- Pause here and wait until the next game frame is drawn
        Core.yield(true)
    end

    print("Animation Complete! 🎉")
end)

Why Use Core.yield(true) Over Event.ENTER_FRAME?

Traditionally, game loops use Event.ENTER_FRAME listeners. While event listeners are great, Core.yield(true) provides significant benefits for multi-step animations:

  1. Linear Logic: You can sequence actions naturally. For example, you can slide a character right, Core.yield(1) to pause for a second, and then fade them out using a Core.yield(true) loop—all within a single block of code
  2. Local Variables Retention: All your loop variables stay safely within the function scope. You don't have to pollute your global space with variables like isAnimating or targetX

See also

Core.asyncCall