axmol v3 migrate guide

axmol v3 removes all APIs that were deprecated in 2.x, and performs a substantial architectural refactor (new RHI layer, unified pointer input, reorganized scene graph, rewritten physics). This guide lists the changes you need to apply when porting a v2.x (2.x LTS) project to v3.

Status: compiled from a full source diff between release/2.x (v2.11.6) and dev (v3 beta1). Every entry below was verified against the actual headers; items that could not be confirmed are explicitly marked unverified.

axmol/axmol.h still exists and is still the "everything" umbrella header.

// v2
#include "base/Director.h"
#include "2d/Node.h"
#include "2d/Sprite.h"
#include "ui/UIButton.h"

// v3
#include "axmol/base/Director.h"
#include "axmol/scene/Node.h"
#include "axmol/2d/Sprite.h"
#include "axmol/ui/Button.h"

Director loses a lot of 2.x compatibility surface.

Correction to earlier drafts of this page: there is no Director::worldToScreen / Director::screenToWorld in v3 (verified: zero occurrences repo-wide). convertToGL / convertToUI were simply removed; use the new canvas helpers (getCanvasSize() / canvasToPixels() / screenToCanvas()) instead.

// v2
int main(int argc, char** argv)
{
    AppDelegate app;
    return Application::getInstance()->run();
}

// v3
int main(int argc, char** argv)
{
    AppDelegate app;
    return Application::getInstance()->launch(argc, argv);   // NEW: launch(argc, argv)
}

ApplicationCore::run() is still the per-platform loop entry, but user code now calls launch(int argc, tchar_t** argv), which parses arguments into the new ax::CommandLineArgs (axmol/platform/CommandLineArgs.h).

initGfxContextAttrs() is gone; it is replaced by applicationWillLaunch() plus the static setContextAttrs() on ApplicationCore.

// v2
void AppDelegate::initGfxContextAttrs()
{
    GfxContextAttrs gfxContextAttrs = {8, 8, 8, 8, 24, 8, 0};
    RenderView::setGfxContextAttrs(gfxContextAttrs);
    Device::setPreferredOrientation(Device::Orientation::SensorLandscape);
}

// v3
void AppDelegate::applicationWillLaunch()
{
    setLogFmtFlag(ax::LogFmtFlag::Full);

    // optional: pick an RHI backend instead of Auto
    // ax::rhi::GraphicsCore::setPreferredBackend(ax::rhi::GraphicsBackend::Auto);

    ContextAttrs contextAttrs = {.debugLayerEnabled = false,
                                 .powerPreference   = PowerPreference::HighPerformance};
    // contextAttrs.vsync = false;                       // V-Sync on by default since 2.2
    // contextAttrs.renderScaleMode = RenderScaleMode::Physical;  // high-DPI
    setContextAttrs(contextAttrs);

    Device::setPreferredOrientation(Device::Orientation::SensorLandscape);
}

Other additions: applicationWillLaunch(), applicationWillQuit() (new in 2.10, still present), registerVulkanInterop(), releaseXRDriver(), ApplicationCore::getDirector().

RenderViewImpl is gone. The platform-independent base is now ax::RenderViewCore, and each platform ships a concrete class named ax::RenderView:

// v2
renderView = RenderViewImpl::createWithRect(title, Rect(0, 0, w, h), 1.0F, true);
director->setRenderView(renderView);
renderView->getFrameSize();

// v3
renderView = RenderView::createWithRect(title, Rect(0, 0, w, h), 1.0F, true);
director->setRenderView(renderView);
renderView->getRenderSize();          // preferred

RenderViewCore API changes:

New view events: RenderViewCore::EVENT_WINDOW_{POSITIONED,RESIZED,FOCUSED,UNFOCUSED,CLOSE,CURSOR_ENTER}.

// v2
virtual void draw(Renderer* renderer, const Mat4& transform, uint32_t flags);
virtual void visit(Renderer* renderer, const Mat4& parentTransform, uint32_t parentFlags);

// v3
virtual void draw(const SceneRenderState& state, const Mat4& transform, uint32_t flags);
virtual void visit(const SceneRenderState& state, const Mat4& parentTransform, uint32_t parentFlags);

SceneRenderState (defined in axmol/scene/Node.h) bundles the renderer and the camera/view data for the current pass:

struct AX_DLL SceneRenderState
{
    Renderer* renderer   = nullptr;
    const Camera* camera = nullptr;
    SceneViewData view;          // { view, projection, viewProjection, position }
    unsigned short cameraFlag    = 0;
    bool viewOverridden          = false;

    Renderer* getRenderer() const;
    const Camera* getCamera() const;
    const SceneViewData& getView() const;
    const Mat4& getViewMatrix() const;
    const Mat4& getProjectionMatrix() const;
    const Mat4& getViewProjectionMatrix() const;
};

struct AX_DLL SceneViewData
{
    Mat4 view, projection, viewProjection;
    Vec3 position;
    static SceneViewData fromCamera(const Camera& camera);
    static SceneViewData fromMatrices(const Mat4& view, const Mat4& projection, const Vec3& position);
};

Concrete migration (DrawNode::draw from the engine itself):

// v2
void DrawNode::draw(Renderer* renderer, const Mat4& transform, uint32_t flags)
{
    updateUniforms(transform, _customCommandTriangle);
    _customCommandTriangle.init(_globalZOrder);
    renderer->addCommand(&_customCommandTriangle);
}

// v3
void DrawNode::draw(const SceneRenderState& state, const Mat4& transform, uint32_t flags)
{
    updateUniforms(state, transform, _customCommandTriangle);   // now takes the state too
    _customCommandTriangle.init(_globalZOrder);
    state.getRenderer()->addCommand(&_customCommandTriangle);
}

This is the largest behavioral change. Event::Type::TOUCH and ::MOUSE collapse into Event::Type::POINTER; Touch, EventTouch and EventMouse are deleted.

EventListener::ListenerID changed from std::string to std::string_view.

// v2 — one by one
auto listener = EventListenerTouchOneByOne::create();
listener->setSwallowTouches(true);
listener->onTouchBegan = AX_CALLBACK_2(Paddle::onTouchBegan, this);
listener->onTouchMoved = AX_CALLBACK_2(Paddle::onTouchMoved, this);
listener->onTouchEnded = AX_CALLBACK_2(Paddle::onTouchEnded, this);
// bool Paddle::onTouchBegan(Touch* touch, Event* event)

// v3
auto listener = PointerEventListener::create();
listener->onPointerDown = AX_CALLBACK_1(Paddle::onPointerDown, this);
listener->onPointerMove = AX_CALLBACK_1(Paddle::onPointerMove, this);
listener->onPointerUp   = AX_CALLBACK_1(Paddle::onPointerUp, this);
// bool Paddle::onPointerDown(PointerEvent* event)

• onTouchBegan→onPointerDown, onTouchMoved→onPointerMove, onTouchEnded→onPointerUp, onTouchCancelled→onPointerCancel, onMouseDown→onPointerDown, onMouseUp→onPointerUp, onMouseMove→onPointerMove, onMouseScroll→onPointerScroll.
• All callbacks drop the trailing Event* argument → AX_CALLBACK_2 becomes AX_CALLBACK_1.
• setSwallowTouches / setSwallowMouse are removed: returning true from onPointerDown now claims pointer capture for (pointerId, button); for scroll use event->stopPropagation().
• There is no "all at once" listener. You receive one PointerEvent per pointer — key your own state on event->getPointerId().
• New optional onPointerHitTest — std::function<bool(PointerEvent*, Vec3*)>.

// v2
listener->onKeyPressed = [](ax::EventKeyboard::KeyCode code, ax::Event* e) { … };
// v3
listener->onKeyPressed = [](ax::KeyboardEvent* e) { auto code = e->getKeyCode(); … };

onKeyRepeat is new; KeyboardEvent::getKeyCode() is now public (it was private in v2).

// v2
IMEDispatcher::sharedDispatcher()->dispatchInsertText(text, len);
// v3
InputSystem::getInstance()->dispatchInsertText(std::string_view{text});

• insertText(const char*, size_t) → insertText(std::string_view)
• deleteBackward(size_t) → deleteBackward(unsigned int)
• canAttachWithIME() / canDetachWithIME() are now const
• getContentText() removed
• IMEKeyboardNotificationInfo::begin/end → single keyboardFrame
• new: updatePreeditText(), performEditAction(), hitTestWithIME()
• InputSystem::getInstance() (there is no Director::getInputSystem()), also owns setMultiTouchEnabled(), setInteractive(), and getLastPointerPosition()

Controller itself is unchanged. The listener callbacks changed:

// v2: std::function<void(Controller*, int keyCode, Event*)>
// v3: std::function<void(ControllerEvent*)>   // e->getController(), e->getKeyCode()

TextFieldTTF is removed in v3 — use the new ui::InputField.

The whole renderer/backend tree was replaced by rhi. There is no backend:: namespace left (verified: zero occurrences in v3).

// v2
auto* drv = ax::backend::DriverBase::getInstance();
// v3
auto* drv = ax::rhi::GraphicsCore::device();   // convenience macro: axdrv

GraphicsCore is the new system-level entry point (axmol/rhi/GraphicsCore.h):

GraphicsCore::setPreferredBackend(GraphicsBackend backend);      // Auto|OpenGL|D3D11|D3D12|Vulkan|Metal
GraphicsCore::setBackendPriority(GraphicsBackend, int prio);
GraphicsCore::setVulkanMinAndroidApiLevel(int apiLevel);         // default 31
GraphicsCore::setVulkanInterop(VulkanInterop*);                  // OpenXR sharing
GraphicsCore::initialize(); / activate(); / shutdown();
GraphicsCore::device(); backend(); isOpenGL(); isMetal(); isD3D11(); isD3D12(); isVulkan();
GraphicsCore::shaderLanguage(); shaderProfile(); shaderILProfile();

• ax::ProgramManager moved from renderer/backend/ProgramManager.h to renderer/ProgramManager.h and is now in namespace ax (not ax::backend).
• Program now exposes getActiveVertexInputs(), getActiveTextureInfos(), getActiveSamplerInfos(), getSamplerBindings(), getActiveStorageBufferInfos(), getComputeLocalSize(), getProgramType(), getProgramId().
• ProgramState: setTexture(int location, int slot, rhi::Texture*), setTextureArray(...), setUniform(const rhi::UniformLocation&, const void*, size_t), setUniformBlock(...), getUniformLocation(std::string_view | rhi::Uniform), clone().

// v2
backend::TextureBackend* tex = sprite->getTexture()->getBackendTexture();
// v3
rhi::Texture* tex = sprite->getTexture()->getRHITexture();

Shaders are no longer authored as GL/GLSL strings handed to newProgram(). v3 compiles shaders ahead of time with axslc and ships binary Data chunks consumed by GraphicsDevice::createProgram(Data, Data). See docs/hlsl-spec.md, docs/hlsl-faq.md and the wiki page Shaders in Axmol3 for the HLSL-based authoring rules.

RenderCommand::init() gained a const SceneViewData& parameter — this affects every *Command subclass:

// v2
void init(float globalZOrder, const Mat4& modelViewTransform, unsigned int flags);
// v3
void init(float globalZOrder, const Mat4& modelViewTransform, unsigned int flags, const SceneViewData& view);

Affected: CustomCommand::init, CallbackCommand::init, QuadCommand::init, TrianglesCommand::init, MeshCommand::init.

RenderTexture was rewritten:

// v2  — RenderTexture is a Node you begin()/end()
auto* rt = RenderTexture::create(w, h);
rt->beginWithClear(0,0,0,0);
rt->end();

// v3  — RenderTexture derives from Texture2D; rendering scope is RenderTexturePass
auto* rt = RenderTexture::create(director->canvasToPixels(size), rhi::PixelFormat::RGBA8);
auto scope = RefPtr<RenderTexturePass>(RenderTexturePass::obtain(rt), tlx::adopt_object);
scope->begin();          // begin(const Camera* camera = nullptr)
…                        // draw
scope->end();

Other changes: create(..., PixelFormat) now takes rhi::PixelFormat; newImage(cb, eglCacheHint) → newImage(cb); getClearColor() returns const Color&.

So the wiki note triangles.indices[i].vertices => triangles.indices[i].position should read:

// v2
quad.bl.vertices  = …;  quad.bl.colors = …;  quad.bl.texCoords = …;
// v3
quad.bl.position  = …;  quad.bl.color  = …;  quad.bl.texCoord  = …;

Note the field order changed (position, texcoord, color) — do not just rename, check layout dependent code (custom vertex writing, memcpy, AutoPolygon::calculateUV, …).

There are no compatibility aliases for these names — ui/UIButton.h will simply fail to compile.

ui::EditBox now derives from InputDelegate instead of IMEDelegate, and lives in axmol/ui/EditBox/EditBox.h.

Both 2D and 3D physics were replaced with new component-based APIs.

CMake: AX_ENABLE_3D_PHYSICS → AX_ENABLE_PHYSICS_3D.

New or renamed options (compare CMakeOptions.md in both branches):

Platform macros: AX_PLATFORM_PC → AX_PLATFORM_GLFW (cpp-tests now guard GLFW-only code with it).

extensions/axmol-ext.h still exists and now also pulls in the SVG extension.

• Multi-backend RHI: OpenGL(ES), Metal, D3D11, D3D12, Vulkan — selectable at build (AX_RENDER_API) and/or runtime (GraphicsCore::setPreferredBackend).
• Compute shaders: rhi::ComputePipeline, GraphicsContext::dispatch().
• VR / OpenXR: axmol/vr/*, AX_ENABLE_VR, XRInputEvent.
• Unified pointer input with pressure/pen/ray support and XR input events.
• WeakPtr, JobSystem, InputSystem, Environment, CommandLineArgs, SceneCompositor, RenderTexturePass, SamplerRegistry, VertexLayoutManager, MeshDataCache.
• New widgets: ui::InputField, ui::TabView, ui::VideoPlayer with pluggable VideoController, ui::RadioButtonGroup.
• Tracy profiler backend (AX_PROFILER_BACKEND=TRACY).

1. Re-point every include: core/… → axmol/…, 2d/{Node,Scene,Camera,Component*} → scene/…, renderer/backend/… → rhi/…, ui/UI* → ui/*.
2. Fix Color3B/Color4B/Color4F → Color32/Color, Quaternion → Quat, V3F_C4B_T2F → V3F_T2F_C4B (mind the field reorder).
3. Fix Node::draw/visit overrides to take const SceneRenderState&; get the renderer via state.getRenderer().
4. Convert touch/mouse listeners to PointerEventListener (drop the Event* argument, remove setSwallowTouches, key multi-touch on getPointerId()).
5. Port backend:: → rhi:: (DriverBase::getInstance() → GraphicsCore::device() / axdrv, CommandBuffer → GraphicsContext, new* → create*, PixelBufferDescriptor → PixelBufferDesc).
6. Update the app delegate (applicationWillLaunch + setContextAttrs) and main() (run() → launch(argc, argv)).
7. Replace Configuration → Environment, StringUtils::format → fmt::format, AsyncTaskPool → getJobSystem(), TextFieldTTF → ui::InputField.
8. Rewrite physics code against physics/2d (box2d) and physics/3d (Jolt).
9. Update your CMake options (AX_RENDER_API, AX_ENABLE_PHYSICS_3D, AX_ENABLE_VIDEO, …).