axmol/CC_LUA_ENGINE_README.mdown

Cocos2d-x *NEW* Lua Engine README

Main features

• Support autorelease CCObject object.
• Call Lua function from C++ (local, global, closure), avoid memory leaks.
• Add CCNode:setPosition(x, y), CCNode::getPosition() huge performance boost.
• Remove needless class and functions from tolua++ .pkg files, improved performance.
• CCMenuItem script callback.
• CCNode onEnter/onExit events handler.
• CCLayer touch & multi-touches events handler.
• Build-in Lua modules: cjson, luasocket.

Changes

• [del] remove old script support from all
• [add] ccConfig.h, define CC_LUA_ENGINE_ENABLED, CC_LUA_ENGINE_DEBUG macro
• [add] CCPlatformMacros.h, define LUALOG macro
• [add] CCObject::m_uLuaID used for Lua VM tracking C++ object
• [add] CCObject::~CCObject() call CCLuaEngine::removeCCObjectByID()
• [add] CCNode add some methods for fast read/write position
  const CCPoint& getPositionLua(void);
  void getPosition(float* x, float* y);
  float getPositionX(void);
  float getPositionY(void);
  void setPositionX(float x);
  void setPositionY(float y);
  void setPosition(float x, float y);
  void setPositionInPixels(float x, float y);
• [add] CCNode::getChildrenCount() for Lua
• [add] CCNode::registerScriptHandler() enable onEnter/onExit event script callback
• [add] CCNode::unregisterScriptHandler()
• [add] CCMenuItem::registerScriptHandler()
• [add] CCMenuItem::unregisterScriptHandler()
• [add] CCMenuItem::activate() default implements call script callback if exist
• [add] CCMenuItem::m_uScriptHandlerFuncID save Lua function reference
• [add] CCLayer::m_uScriptHandlerFuncID save Lua function reference
• [add] ccTouchBegan(), ccTouchMoved(), ccTouchEnded(), ccTouchCancelled(), ccTouchesBegan(), ccTouchesMoved(), ccTouchesEnded(), ccTouchesCancelled() default implements are used to call script callback if exist
• [add] CCLayer::registerScriptTouchHandler()
• [add] CCLayer::unregisterScriptTouchHandler()
• [add] CCTimer::timerWithScriptFuncID()
• [add] CCTimer::initWithScriptFuncID()
• [add] CCTimer::m_uScriptFuncID
• [add] CCScheduler::scheduleScriptFunc()
• [add] CCScheduler::unscheduleScriptEntry()
• [add] CCScheduler::m_pScriptEntries
• [add] add Lua module: cjson, luasocket

---

How to use

CCNode onEnter/onExit events handler

CCNode:registerScriptHandler() register callback function for onEnter/onExit events。Callback function auto unregister after onExit() called.

local function createScene()
    local scene = CCScene:node()

    

    local function sceneEventHandler(eventType)
        if eventType == kCCNodeOnEnter then
            if scene.onEnter then scene:onEnter() end
        else
            if scene.onExit then scene:onExit() end
        end
    end

    scene:registerScriptHandler(sceneEventHandler)

    return scene
end

local scene = createScene()
function scene:onEnter()
    print("on scene enter")
end
fucntion scene:onExit()
    print("on scene exit")
end

CCDirector:sharedDirector():runWithScene(scene)

Touch and multi-touches events handler

local function onTouch(eventType, x, y)
    -- eventType is CCTOUCHBEGAN, CCTOUCHMOVED,
    -- CCTOUCHENDED or CCTOUCHCANCELLED
    -- x, y is touch position (use cocos2d-x/OpenGL coordinate)
end

local function onTouches(eventType, touches)
    -- touches is x1, y1, x2, y2, x3, y3, ...
    for i = 1, #touches, 2 do
        local x, y = touches[i], touches[i + 1]
        print(x, y)
    end
end

local layer = CCLayer:node()

-- enable touch events callback
layer:registerScriptTouchHandler(onTouch, false)  -- for single touch
OR
layer:registerScriptTouchHandler(onTouches, true) -- for multi-touches

-- remove touch events callback
layer:unregisterScriptTouchHandler()

Schedule callback

scheduler module:

module("scheduler", package.seeall)

scheduler = CCScheduler:sharedScheduler()

function enterFrame(listener, isPaused)
    return scheduler:scheduleScriptFunc(listener, 0, isPaused or false)
end

function schedule(listener, interval, isPaused)
    return scheduler:scheduleScriptFunc(listener, interval, isPaused or false)
end

function unschedule(handle)
    scheduler:unscheduleScriptEntry(handle)
end
remove = unschedule

function performWithDelay(time, listener)
    local handle
    handle = scheduler:scheduleScriptFunc(function()
        scheduler:unscheduleScriptEntry(handle)
        listener()
    end, time, false)
    return handle
end

use:

require("scheduler")

local handle -- save script callback ID

-- schedule every frame update
local frameCount = 0
local function onEnterFrame(dt)
    -- dt is float number
    frameCount = frameCount + 1
    if frameCount >= 60 then
        -- unschedule callback
        scheduler.unschedule(handle)
    end
end

handle = scheduler.enterFrame(onEnterFrame)

-- print message after delay
scheduler.performWithDelay(0.5, function()
    print("delay 0.5 second")
end)

Create menu

local function onPlayButtonTap()
    print("PLAY NOW")
end

local button = CCMenuItemSprite:itemFromNormalImage("playButton.png", "playButton.png")
button:setPosition(100, 200)
button:registerScriptHandler(onPlayButtonTap)

local menu = CCMenu:node()
menu:addChild(button)
scene:addChild(menu)

---

TODO

• When C++ object deleted, remove Lua userdata
• Improvement tolua_isusertype()