Migration Guide for PR 3228

PointerEvent API Changes

The following method renames require updating all call sites:

Screen-space methods

// Before
event->getScreenLocation();        // Vec2
event->getPreviousScreenLocation(); // Vec2
event->getStartScreenLocation();    // Vec2

// After
event->getPoint();
event->getPrevPoint();
event->getStartPoint();

World-space methods

// Before
event->getLocation();         // Vec2 (actually world space!)
event->getPreviousLocation(); // Vec2
event->getStartLocation();    // Vec2

// After
event->getWorldPoint();
event->getPrevWorldPoint();
event->getStartWorldPoint();

Behavioral change: getWorldPoint() now computes the world position using the per-camera ray (Camera::screenToRay) rather than Director::screenToWorld(). In multi-camera setups, the result may differ. The ray is set by EventDispatcher before dispatch, so you can also use event->getRay() for custom intersection logic.

---

Camera Changes

Camera::create() now takes a CameraMode parameter

// Before (default camera from Director projection)
auto camera = Camera::create();

// After (explicit mode)
auto camera = Camera::create(CameraMode::Classic);
Camera::create(CameraMode::Perspective);  // if you had custom projection

initDefault() renamed to initClassic()

// Before
camera->initDefault();

// After
camera->initClassic();

AX_ENABLE_3D guards removed from Camera

screenToRay() and isVisibleInFrustum() are now always available — no need to #if defined(AX_ENABLE_3D) around them.

---

Removed Director APIs

Removed	Replacement
Director::setProjection(Projection)	Camera::create(mode)
Director::screenToWorld(Vec2)	Camera::deprojectScreenToWorld(Vec3)
Director::worldToScreen(Vec2)	Camera::projectWorldToCanvas(Vec3)
Director::EVENT_PROJECTION_CHANGED	Per-camera ray recomputation
axmol.gl.projection env var	Explicit CameraMode in Camera::create()

Note: If you were listening to EVENT_PROJECTION_CHANGED to react to projection changes, you should now manage camera state directly via the Camera API.

---

Hit-Testing Signature Change

Custom onPointerHitTest implementations must drop the camera parameter:

// Before
bool onPointerHitTest(PointerEvent* event, const Camera* camera, Vec3* outWorldHit);

// After
bool onPointerHitTest(PointerEvent* event, Vec3* outWorldHit);

Obtain camera info from the event instead:

const Camera* camera = event->getCamera();
const Ray&    ray    = event->getRay();

---

Math Includes

If you were including from axmol/3d/:

// Before
#include "axmol/3d/AABB.h"
#include "axmol/3d/Frustum.h"
#include "axmol/3d/OBB.h"
#include "axmol/3d/Plane.h"
#include "axmol/3d/Ray.h"

// After
#include "axmol/math/AABB.h"
#include "axmol/math/Frustum.h"
#include "axmol/math/OBB.h"
#include "axmol/math/Plane.h"
#include "axmol/math/Ray.h"

These types are no longer guarded by AX_ENABLE_3D, so conditional includes can be removed.

---

Types.h / Vertex.h

Tex2F, Quad2, Quad3, V2F_T2F_C4B, and similar vertex structs moved from axmol/base/Types.h to axmol/math/Vertex.h.

If you were using them and only including Types.h, you may need to add:

#include "axmol/math/Vertex.h"

Types.h still includes Vertex.h transitively, so existing code should continue to compile.

---

Lua Test Updates

If you maintain Lua scripts that use PointerEvent:

Before	After
event:getLocation()	event:getWorldPoint()
event:getScreenLocation()	event:getPoint()

All 61 occurrences in tests/lua-tests/ have already been updated in this PR.