Nanfeng

Notes on software development, code, and curious ideas

Getting Started with Cocos2d-x 3.17 Lua Game Development

In
A practical Cocos2d-x 3.17 Lua reference for scenes, sprites, UI, touch, storage, animation, and geometry.

This guide targets Cocos2d-x 3.17 with Lua. Project-generation commands and SDK paths vary by operating system, but the engine concepts below are stable within the 3.x bindings.

Screen design and sprites

Configure the design resolution once and choose an appropriate policy for the supported aspect ratios. Place important controls inside a safe layout region rather than assuming one fixed screen size.

1
2
3
local sprite = cc.Sprite:create("images/hero.png")
sprite:setPosition(display.cx, display.cy)
self:addChild(sprite)

Buttons and touch

1
2
3
4
5
6
local button = ccui.Button:create("button.png")
button:setPosition(display.cx, 120)
button:addClickEventListener(function()
    print("clicked")
end)
self:addChild(button)

For custom touch handling, create cc.EventListenerTouchOneByOne, return true only when the node claims the touch, and handle began, moved, ended, and cancelled states. Convert coordinates into the target node’s local space before hit testing.

Storage

Small preferences can use cc.UserDefault:

1
2
3
4
local store = cc.UserDefault:getInstance()
store:setIntegerForKey("highScore", 1200)
store:flush()
local score = store:getIntegerForKey("highScore", 0)

Do not treat it as secure storage. Structured saves need versioning, validation, atomic writes, and platform-appropriate protection for sensitive values.

Actions and scheduling

1
2
3
4
sprite:runAction(cc.Sequence:create(
    cc.MoveBy:create(0.5, cc.p(100, 0)),
    cc.FadeOut:create(0.25)
))

Use the scheduler for repeated updates and unschedule callbacks when their owner exits. Frame animation uses cc.Animation and cc.Animate; UI timelines use CSB actions.

Geometry

Use cc.rectContainsPoint for point tests and cc.rectIntersectsRect for axis-aligned rectangle overlap. Direction angles can be calculated with math.atan2 where provided by the runtime or the equivalent math.atan(y, x) form in newer Lua versions. Always verify coordinate spaces before comparing geometry.

Build scenes from small nodes with clear ownership, retain only needed references, and centralize cleanup for listeners, timers, textures, and asynchronous callbacks.

+