Upgrading Defold versions
This is the standing runbook for moving a project from one pinned Defold API
surface to another, followed by one section per release recording exactly what
changed in it. The runbook is version-agnostic — read <old> as the version you
ship today and <new> as the one you are moving to — so it stays true for every
upgrade; the per-release sections below carry the concrete facts.
Pair it with Pinning the Defold target: pin the old
surface first to reproduce today's build, then flip the pin to <new> and let
the compiler point at everything that moved. The curated availability facts
behind the lifecycle notes live in packages/types/api-availability.json; each
symbol keeps a stable heading on this page so the API lifecycle badges can link a
reader straight to it.
Reproduce, then flip the target
Reproduce the current build against the exact old surface, then re-run the same command against the new one to surface every removed call as a compile error:
# what you ship today
bunx @defold-typescript/cli build --defold-target <old>
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target <new>Once the project compiles clean, record the target in package.json so every
later build, watch, and resolve agrees:
// package.json
{
"defold-typescript": { "defold-target": "<new>" }
}Verification
After flipping the pin, prove the upgrade end to end:
-
Type-check against
<new>— every removed call in that release's section is now a compile error, so a clean type-check means no removed API survives in your source:bunx @defold-typescript/cli build --defold-target <new> -
Confirm the resolved target and surface in the
--jsonenvelope report<new>, as described in Pinning the Defold target. -
Build and run the game in the matching Defold editor and walk the rendering/platform changes listed for that release by hand, since those cannot be caught by the compiler.
Reading the API reference over a range
The API reference covers a range of Defold releases rather than one, so a single page can answer "what changed between the version I ship and the one I am moving to". Two dropdowns pick the range:
- From is the oldest release in view. Narrowing it hides the symbols that had already gone by then, sidebar counts included.
- To is the newest release in view. It also decides which declaration a symbol renders with: the newest declaration made inside the range, or the signature the symbol was built with when the range declares none, so a deprecated symbol keeps its full declaration rather than a weaker one.
Setting both to the same release is the exact-version view — everything that
release carries, and nothing else, as on the 1.13.0 go
page. The unprefixed
/api/<namespace> is the full range across every tracked release,
/api/<version>/<namespace> is the range ending at that version, and appending
?since=<version> states the lower bound explicitly, which the sidebar's API
links then keep from page to page. Without it the page starts
at the From you last picked, or at the oldest tracked release if you never
picked one.
A page that spans releases carries two vocabularies, and they answer different questions:
- The version note is absolute. It names the release the symbol really
arrived in or left, which may sit outside the range you selected —
Since Defold 1.13.0means 1.13.0, whatever theFrombound says. Each note line leads with theN/C/Dchip for that fact across every tracked release, so it stays visible when the heading's range-relative chip hides. - No version note means "in every tracked release". Such a symbol may be far
older than the oldest release tracked here; the API index states which releases
those are, and the
Fromdropdown names the oldest of them. - The colored marker and its counts are relative to the range. The
N/C/Dmarkers on a symbol, the counts beside a namespace title and the counts in the sidebar all describe movement inside the selected range:Newreaches theTorelease but not theFromone, andChangedmoved some other way in between. So an unmarked symbol did not move inside your range — it may still carry an absolute version note — and settingFromandToto the same release marks nothingNeworChanged, because a release has not moved relative to itself. Deprecatedis bounded byToalone. A symbol shows it when the deprecation had already happened by theTorelease, whateverFromis set to; a deprecation landing afterTodoes not mark a symbol before it happened. That bound is why a same-release range can still markDeprecated: the symbol really is deprecated in the release you are reading.- A changed signature is history, not an overload. A function whose signature
changed between releases renders under its current signature, with one
Signature changed in Defold <version> — before: …line per form it replaced, as onb2d.get_world. A form dropped without a replacement shows as aRemoved in Defold <version>: …line. Both lines lead with theCchip in place of a bullet and are absolute, like the version note, and narrowingFrompast the old form hides its line.
Release notes
Each release below opens with a <!-- release: <version> --> marker and one
## Defold <version> heading, with that release's notes nested under it. The
release-readiness gate reads every marked section covering the hop from the
previous stable release up to the one being shipped, so each release keeps its
own "what changed" notes under its own version — a change is never relabelled
forward onto a later release. A note filed under the release you are upgrading
from is not migration coverage. Add a section per release rather than a new
page.
Defold 1.13.0
Moving a project from 1.12.4 removes a handful of Lua APIs, re-signatures a few others, changes some source/asset expectations, and shifts a few rendering and platform defaults. Each change below carries actionable migration guidance and a way to verify it.
The runbook above, with this release's concrete targets:
# what you ship today
bunx @defold-typescript/cli build --defold-target 1.12.4
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target 1.13.0Changed Lua API signatures
These Lua APIs still exist on the 1.13.0 surface — one or more parameter types
changed rather than the symbol being removed, so a call written against 1.12.4
keeps compiling. Because an API page covers a
range, both signatures render adjacently
wherever the range spans the change; narrow the From dropdown to 1.13.0 to see
only what that release still carries.
liveupdate.add_mount
Despite the old Live Update auto-mount framing, liveupdate.add_mount was
not removed — it remains an imperative runtime API on the 1.13.0
liveupdate surface. Its name parameter widened from
string to string | Hash, so a hashed mount name is now accepted alongside a
plain string, and the mount callback is typed more precisely. Compare the current
signature with the historical one on the 1.12.4 liveupdate
page.
liveupdate.remove_mount
liveupdate.remove_mount likewise remains; its name parameter widened from
string to string | Hash so a hashed mount name resolves the mount to tear
down. The 1.12.4 liveupdate page keeps the old
single-string signature for comparison.
Removed Lua APIs and constants
Each removed symbol is a compile error against the 1.13.0 surface. Its frozen signature stays discoverable on the historical 1.12.4 API pages; the current-surface namespace pages linked below show what replaced it.
model.material
The single-slot model.material property is removed. A model can carry several
material slots, so address a slot by name with the component material APIs on the
current model surface instead of the one blanket property; the
removed property's frozen shape stays on the 1.12.4 model
page.
Deprecated Lua APIs
These APIs still compile and run against the 1.13.0 surface but are marked deprecated in the engine reference. No replacement is announced upstream, so nothing is forced right now — treat them as candidates for removal in a future release and avoid them in new code.
model.reset_constant,sprite.reset_constant,tilemap.reset_constant. The per-component "reset a shader constant" helpers are deprecated in 1.13.0. They keep working and there is no documented successor to migrate to yet, so no action is required today.acquire_camera_focus,release_camera_focus(camera messages). The two camera-focus messages are deprecated in 1.13.0. They still post and route with their existing payloads, andbuiltin-messages.d.tsnow marks them@deprecated, somsg.postcalls that name them keep compiling. No successor is announced, so no action is required today — avoid them in new code.
Source and project migrations
These changes touch assets and project configuration rather than the typed Lua surface, so the compiler cannot flag them — audit them by hand.
- Collada removal. Collada (
.dae) mesh import is removed. Re-export any remaining Collada meshes to glTF (.gltf/.glb) before upgrading; the engine no longer loads the old format. - glTF transform and re-centering. glTF import no longer silently re-centers or bakes node transforms the way older versions did. A model that relied on the old re-centering may shift position; re-check pivots and any code that assumed the previous origin, and re-bake transforms in your DCC tool if needed.
- Hashed mount names. Live Update mount names are now hashes rather than raw strings. Anywhere you compared or logged a mount name as a string, switch to the hashed identity the resource system reports.
- Spine extension 4.6.0 minimum. Spine support moved fully into the external
Spine extension, and 1.13.0 requires Spine extension 4.6.0 or newer. Bump
the Spine dependency in
game.projectto at least4.6.0; older extension versions will not build.
Rendering and platform behavior
Defaults changed here. Nothing is a Lua API removal, but the rendered result or the target platform behaves differently.
- Counter-clockwise component winding. Component triangle winding is now counter-clockwise. Custom render setups or shaders that assumed clockwise front-face winding may cull the wrong side; flip the winding or face-culling state in affected materials.
- Particle-effect culling. Particle effects now participate in view culling, so an effect fully outside the camera frustum can stop drawing. If an effect must always render, keep its emitter within view bounds or account for the new culling in your render predicate.
- Android Vulkan default. Android now defaults to the Vulkan graphics
adapter. If a device or shader misbehaves under Vulkan, verify against the
Vulkan path first and fall back to OpenGL explicitly in
game.projectonly when a device needs it. - HTML5 splash containment. The HTML5 splash screen is now contained within the canvas rather than spanning the page. Custom HTML shells that positioned the splash against the full window should re-check their layout.
- asm.js removal. The HTML5 build no longer emits an asm.js fallback; builds are WebAssembly-only. Drop any asm.js-specific loader branches from a custom HTML5 shell, since only the WebAssembly artifact is produced.
Defold 1.13.1
Defold 1.13.1 is a patch over 1.13.0, which stays a shipped surface beside it: nothing was removed, nothing was deprecated, and the only Lua API deltas are the two additive changes below. A project already on 1.13.0 needs no source migration — move the pin and rebuild. A project on 1.12.4 migrates through the 1.13.0 notes above as well.
The runbook above, with this release's concrete targets:
# what you ship today
bunx @defold-typescript/cli build --defold-target 1.13.0
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target 1.13.1Added Lua APIs
collectionproxy.load
collectionproxy.load is new on the 1.13.1
collectionproxy surface — the 1.13.0
collectionproxy page has no such function.
It is purely additive, so no existing call needs changing; a project that wants it
must pin --defold-target 1.13.1 or newer.
Changed Lua API signatures
gui.set
gui.set's value parameter accepts nil alongside the number and vector types
it already took, so a property can be cleared rather than only reassigned.
Existing calls are unaffected — the change is a widening. The current signature is
on the 1.13.1 gui surface; the 1.13.0 gui
page shows the narrower one for comparison.
Defold 1.13.2
Defold 1.13.2 is a patch over 1.13.1. Most of its API
changes widen a type or name a table shape that was anonymous before, so code
written against 1.13.1 keeps compiling. A few changes
can break a build: b2d.get_world, b2d.body.get_name and b2d.body.get_next
may return nothing, json.decode returns unknown, and the LuaSocket
getpeername, getsockname and getstats methods return several values instead
of one string. The notes below link the 1.13.1 pages that keep the old
signatures. A project on 1.12.4 migrates through the 1.13.0 and 1.13.1 notes above
as well; the 1.12.4 reference keeps that release's
surface.
The runbook above, with this release's concrete targets:
# what you ship today
bunx @defold-typescript/cli build --defold-target 1.13.1
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target 1.13.2Added Lua APIs
These are additive, so no existing call changes. A project that uses them must
pin --defold-target 1.13.2 or newer.
- Bullet 3D physics. The
bullet3dnamespaces (bullet3d.world,bullet3d.collision_object,bullet3d.rigid_body,bullet3d.shape,bullet3d.constraint) script the 3D physics world directly. They exist only in a project whosegame.projectsets 3D physics. - Rich-text layout objects.
label.get_layout_objectsandgui.get_layout_objectslist the inline sprites and links in a label or text node, and the newtext_object_hovered,text_object_unhoveredandtext_object_clickedmessages report pointer interaction with them. - Collection proxy progress messages.
proxy_loading,proxy_readyandproxy_errorreport the state of a collection proxy load. - Mesh collision shapes.
physics.SHAPE_TYPE_MESHandbullet3d.shape.SHAPE_TYPE_MESHname the triangle-mesh shape kind. - Multisampled render targets. The
render.render_targettable takes asample_countkey, andresource.get_render_target_inforeports it. - Opening a resource at a position.
editor.ui.open_resourcetakes an optionalviewand view-specificargs, such as a one-based{ line: 42 }cursor for the Code and Text views.
Changes that can break a build
b2d.get_world
b2d.get_world now returns Opaque<"b2World"> | undefined, because the world is
absent until physics starts. Check the result, or assert it with ! where the
world is known to exist. The 1.13.1 b2d page keeps the
old signature.
b2d.body.get_name
b2d.body.get_name returns string | undefined, because a body without a name
returns nil. Handle the missing case. Compare the 1.13.1 b2d.body
page.
b2d.body.get_next
b2d.body.get_next returns Opaque<"b2Body"> | undefined, because the last body
in the world list has no next body. End the walk when it returns nothing.
json.decode
json.decode returns unknown instead of a string-keyed table, because a JSON
document can decode to any Lua value. Narrow the result before reading fields
from it, for example with a type guard or a cast to the shape you expect. Compare
the 1.13.1 json page.
socket.client:getpeername
getpeername returns LuaMultiReturn<[host, port, family]> instead of one
string, matching what LuaSocket returns. Destructure it:
const [host, port] = client.getpeername(). The
1.13.1 socket page keeps the old form.
socket.connected:getpeername
Same change as socket.client:getpeername: destructure the host, port and
family.
socket.client:getsockname
getsockname returns LuaMultiReturn<[host, port, family]> instead of one
string. Destructure it the same way as getpeername.
socket.connected:getsockname
Same change as socket.client:getsockname.
socket.master:getsockname
Same change as socket.client:getsockname.
socket.server:getsockname
Same change as socket.client:getsockname.
socket.unconnected:getsockname
Same change as socket.client:getsockname.
socket.client:getstats
getstats returns LuaMultiReturn<[received, sent, age]> as three numbers
instead of one string. Destructure the counts:
const [received, sent, age] = client.getstats().
socket.master:getstats
Same change as socket.client:getstats.
socket.server:getstats
Same change as socket.client:getstats.
Widened signatures
These signatures accept more than before or return a more precise type. A call written against 1.13.1 keeps compiling.
b2d.world.cast_ray
The filter and max_results arguments are optional on every form, and the
filter and hit tables are the named b2d.QueryFilter and b2d.FixtureCastHit
or b2d.ShapeCastHit types. Compare the 1.13.1 b2d.world
page.
b2d.world.cast_ray_closest
Same change as b2d.world.cast_ray: filter is optional on every form.
b2d.world.cast_shape
Same change as b2d.world.cast_ray.
b2d.world.overlap_aabb
Same change as b2d.world.cast_ray, with b2d.Aabb as the box type.
b2d.world.overlap_shape
Same change as b2d.world.cast_ray.
gui.new_texture
The type parameter takes string | image.Type, so an image.TYPE_* constant
passes without a cast. The second return value narrows from number to
gui.Result. Compare the 1.13.1 gui page.
gui.set_texture_data
The type parameter takes string | image.Type, as for gui.new_texture.
image.load
options also accepts a boolean, the older premultiply-alpha flag, and the
options and result tables are the named image.LoadOptions and
image.LoadResult types. Compare the 1.13.1 image
page.
image.load_buffer
Same change as image.load, with image.LoadBufferResult as the result type.
json.encode
json.encode accepts any value, not only a table, and its options table is the
named json.EncodeOptions type.
socket.skip
socket.skip takes any number of values after the count and returns the values
it keeps, so a call with more than three values compiles.
socket.client:close
close returns the number LuaSocket reports instead of void. Existing calls
that ignore the result are unaffected.
socket.connected:close
Same change as socket.client:close.
socket.master:close
Same change as socket.client:close.
socket.server:close
Same change as socket.client:close.
socket.unconnected:close
Same change as socket.client:close.
socket.client:setstats
Every argument is optional and the return is a plain number.
socket.master:setstats
Same change as socket.client:setstats.
socket.server:setstats
Same change as socket.client:setstats.
socket.client:settimeout
The timeout value is optional and the method returns a number instead of
void.
socket.connected:settimeout
Same change as socket.client:settimeout.
socket.master:settimeout
Same change as socket.client:settimeout.
socket.server:settimeout
Same change as socket.client:settimeout.
socket.unconnected:settimeout
Same change as socket.client:settimeout.
Changes to the reference only
The engine reference re-documents these symbols, so the API catalog records a new signature, but the TypeScript declarations you compile against are unchanged. No action is needed.
The reference also re-documents two lifecycle hooks,
which are typed as members of the defineScript and defineGuiScript tables
rather than as go or gui functions. on_input documents action_id as nil
for pointer movement, which the typed hook already declares Hash | undefined,
and the GUI on_message documents its sender argument, which the typed hook
already passes.
b2d.body.get_contact_list
The 1.13.2 reference no longer documents b2d.body.get_contact_list. The typed
surface never declared it, because neither Box2D binding registers it and the
call would raise, so no code changes.
b2d.body.get_world_center
The 1.13.0 and 1.13.1 references typed the return as a number. The declarations
already return Vector3, which the 1.13.2 reference now documents.
go.get
The reference lists string among the values go.get returns and drops the
resource handle. The typed go.get overloads are unchanged; see the 1.13.1 go
page for comparison.
go.set
The reference lists string among the values go.set accepts. The typed overloads
are unchanged.
go.property
The reference lists string among the default values go.property accepts. The
typed overloads are unchanged.
render.render_target
The reference drops the deprecated leading name argument. Both typed forms,
with and without the name, still compile; see the 1.13.1 render
page.
sys.get_config_string
The reference documents that the lookup can return nil. The typed overloads
already return string | undefined without a default and string with one; see
the 1.13.1 sys page.
socket.client
The reference renames the LuaSocket object types to socket_client,
socket_master and socket_unconnected. The handle interface is
socket.SocketClient on every target, so an annotation needs no change, and
its method changes are listed above.
socket.master
Same change as socket.client: the interface is socket.SocketMaster on
every target.
socket.unconnected
Same change as socket.client: the interface is socket.SocketUnconnected on
every target.
Deprecated Lua APIs
These still compile and run against the 1.13.2 surface.
window.WINDOW_EVENT_ICONFIED
The misspelled window.WINDOW_EVENT_ICONFIED is deprecated in favor of
window.WINDOW_EVENT_ICONIFIED, which the reference now documents. The engine
registers both with the same value, and the declarations give them the same
type, so either compares equal to a window.set_listener event and either works
as the isWindowEvent constant. Switch to the correct spelling. The 1.13.1 window page shows only
the old name.
label.get_text,label.set_text. Deprecated in favor of the label component'stextproperty: read it withgo.getand write it withgo.seton the"text"key.
Defold 1.14.0
Defold 1.14.0's Lua API changes only add: nothing was removed, nothing was deprecated and no signature got narrower, so a project on 1.13.2 needs no source change for the Lua API. Move the pin and rebuild. The release also changes engine behavior and project settings that the compiler cannot check, so walk the last two topics below by hand. A project on an older release migrates through the notes above as well.
The runbook above, with this release's concrete targets:
# what you ship today
bunx @defold-typescript/cli build --defold-target 1.13.2
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target 1.14.0Added Lua APIs
These are additive, so no existing call changes. A project that uses them must
pin --defold-target 1.14.0 or newer.
b2d.get_gameobject_id
b2d.get_gameobject_id returns the id of the game object that owns a Box2D
body, on the 1.14.0 b2d surface. It returns
Hash | undefined, because a body created from script belongs to no game
object. Check the result before using it.
bullet3d.get_gameobject_id
bullet3d.get_gameobject_id does the same for a Bullet collision object or
rigid body, on the 1.14.0 bullet3d surface. It
also returns Hash | undefined.
Cubemap render targets
A render target can be a cubemap, and a render script picks the face it draws to. Three additions carry this:
- Face constants.
graphics.CUBEMAP_FACE_POSITIVE_X,graphics.CUBEMAP_FACE_NEGATIVE_X,graphics.CUBEMAP_FACE_POSITIVE_Y,graphics.CUBEMAP_FACE_NEGATIVE_Y,graphics.CUBEMAP_FACE_POSITIVE_Zandgraphics.CUBEMAP_FACE_NEGATIVE_Zname the six faces on the 1.14.0graphicssurface. - The
faceoption. The options table ofrender.set_render_targettakes afacekey typed as one of those constants. It is valid only for a cubemap render target and defaults tographics.CUBEMAP_FACE_POSITIVE_X. - The
typekey. The parameter table ofrender.render_targettakes atypekey, andgraphics.TEXTURE_TYPE_CUBE_MAPcreates the target as a cubemap. A cubemap render target needs equal width and height.
Both keys are optional, so existing calls keep compiling. Compare the 1.14.0
render surface with the 1.13.2 render
page.
Behavior changes with no signature change
These compile unchanged against 1.14.0 and behave differently at run time.
- Accelerometer input is off by default. The
on_inputaction carriesacc_x,acc_yandacc_zonly whenuse_accelerometerunder[input]is enabled ingame.project. A game that reads them must turn the setting on. - Matrix vertex attributes take a matrix. For a custom vertex attribute of a
matrix type,
go.getreturns avmath.matrix4andgo.settakes one, whatever the attribute's size. A 2x2 matrix attribute no longer reads or writes as avmath.vector4.
gui.get_layout_objects
Each layout object's x and y are relative to the text node's pivot and are
not scaled. 1.13.2 measured them from the node's upper-left layout origin. Code
that places something over an inline sprite or link from these values must
start from the pivot and apply the node's scale and rotation itself. See the
1.14.0 gui surface.
label.get_layout_objects
Same change as gui.get_layout_objects, relative to the label's pivot. See the
1.14.0 label surface.
Project and platform migrations
- Scripts always share one Lua state. The Shared State setting is gone from
game.project: game object, GUI and render scripts run in one Lua state. A project that had the setting off now shares globals and the cache of loaded modules between its scripts, so two scripts that set the same global name overwrite each other. - 32-bit Windows is removed. The
x86-win32platform no longer builds. Change any build script that names it tox86_64-win32. - Native extensions need 1.14.0 builds. The engine's native interface changed, so an extension that ships prebuilt libraries, and an extension with an editor plugin, must be updated to a release built for 1.14.0.
Defold 1.14.1
Defold 1.14.1 is a patch over 1.14.0 and the toolchain's
default API target. Its Lua API changes add and widen: every call written
against 1.14.0 keeps compiling, so a project on 1.14.0 needs no source change
for the Lua API. The one removal is the start_record and stop_record
messages, which only an untyped msg.post reaches. The release also changes
shader, render target and GUI behavior, 3D physics shape sizes, iOS window resize
events and the custom iOS Info.plist, and adds a build check on skinned
materials over meshes without skin data. The compiler cannot check any of these,
so walk the last topic below by hand. A project on 1.13.2
migrates through the 1.14.0 notes above as well; the 1.13.2
reference keeps that release's surface.
The runbook above, with this release's concrete targets:
# what you ship today
bunx @defold-typescript/cli build --defold-target 1.14.0
# the same project against the new surface
bunx @defold-typescript/cli build --defold-target 1.14.1Added Lua APIs
These are additive, so no existing call changes. A project that uses them must
pin --defold-target 1.14.1 or newer.
recorder.start
recorder.start records the game window to an MP4 file, on the new 1.14.1
recorder surface. It takes a
recorder.Options table (path, and optional fps and audio) and a
callback that receives recorder.EVENT_STARTED, then recorder.EVENT_STOPPED
or recorder.EVENT_ERROR with a recorder.Result. It returns
LuaMultiReturn<[boolean | undefined, string | undefined]>: true when the
request is accepted, otherwise undefined and the reason. Only desktop debug
engines carry the module; release, headless, mobile and web builds omit it, so
the global is nil there at run time even though the declaration compiles.
recorder.stop
recorder.stop asks the active recording to finalize. Call it after the
callback has received recorder.EVENT_STARTED; the file is ready when the
callback receives recorder.EVENT_STOPPED. It returns the same accepted flag
and reason as recorder.start.
window.get_reserved_areas
window.get_reserved_areas returns the screen areas a camera cutout or the
Dynamic Island covers, as an array of window.ReservedArea (x, y, width,
height in window pixels), on the 1.14.1 window
surface. It reports areas on iOS and Android and returns an empty array
elsewhere. Query it in init and again on window.WINDOW_EVENT_RESIZED.
graphics.CONTEXT_FEATURE_BACKBUFFER_READBACK
graphics.CONTEXT_FEATURE_BACKBUFFER_READBACK is a context feature flag for
backbuffer readback support, on the 1.14.1
graphics surface. It is a member of
graphics.ContextFeature.
Widened Lua APIs
Each of these gains an optional trailing argument, so existing calls keep
compiling. The 1.14.0 sound page and the 1.14.0
sys page keep the older signatures.
sound.set_gain
sound.set_gain takes an optional third properties argument, a
sound.ParameterProperties table. Pass its play_id, the id sound.play
returns, to change one voice; omit it to change every voice and the gain the
component uses for later playback. See the 1.14.1
sound surface. The set_gain message takes the
same play_id.
sound.set_pan
sound.set_pan takes the same optional properties argument, with the same
play_id rule, and the set_pan message takes the same play_id.
sys.reboot
sys.reboot takes two more optional string arguments, arg7 and arg8, and
the reboot message takes the same two fields. See the 1.14.1
sys surface.
Input source
The on_input action table carries source, a Hash of the input device
category: hash("keyboard"), hash("text"), hash("mouse"), hash("touch"),
hash("gamepad") or hash("accelerometer"). Compare it to tell a physical mouse
click from one simulated by touch. InputAction types it as optional, because it
types every pinned target and 1.14.0 and older never send it.
Removed messages
The start_record and stop_record messages to @system are gone; the
recorder module replaces them and writes MP4 instead of VP8. The built-in
message types follow the default target, so they no longer declare either
message. A project pinned to 1.14.0 or older that still posts them does so
through the untyped msg.post arm.
Untyped Lua APIs
debugger.start, which starts the engine debugger's listener, has no
declaration: the 1.14.1 API reference does not document it, and debugger is a
reserved word in TypeScript. Declare it in your project instead, as Calling the
engine debugger from
TypeScript shows.
Behavior and project migrations
These compile unchanged against 1.14.1 and behave differently at run time or at build time.
- GLES 2.0 and WebGL 1 shaders are opt-in.
Exclude GLES 2.0ingame.projectis on by default, so a game that must run on OpenGL ES 2.0 or WebGL 1 has to turn it off. - A render target needs an attachment. A render target resource, or one a render script creates, with no color, depth or stencil attachment is rejected. Give a placeholder render target at least one attachment of at least 1x1.
- Sprites flip around the atlas pivot.
sprite.set_hflipandsprite.set_vflipflip around the pivot set in the atlas, the same way a negative scale does. A sprite with an off-center pivot no longer shifts when flipped, so remove any offset that compensated for the shift. layout_changedarrives afterinit. A GUI script no longer receiveslayout_changedbeforeinit; layout notifications that arrive earlier are combined and delivered onceinitsucceeds.- Legacy Spine GUIs need an updated Spine extension. The Spine-specific GUI migration moved into the extension, so building a legacy Spine GUI needs a Spine extension release made for 1.14.1.
- A custom iOS
Info.plistneeds new keys. AddUIApplicationSupportsIndirectInputEventsset to true, and move the generated orientation list into the newDefoldSupportedInterfaceOrientationskey, to match the built-in template. - 3D physics shapes are sized in game units.
physics.get_shapereturns 3D sphere, box and capsule dimensions in game units, independent ofphysics.scale, andphysics.set_shapeappliesphysics.scaleto a 3D sphere radius. Drop any compensation for either. - A skinned material needs a mesh with skin data. A model that assigns a
skinned material, one whose shader reads
bone_weightsorbone_indices, to a mesh with no skin data fails the build, where on some graphics backends, such as Metal, it crashed at run time. Give that mesh a non-skinned material. Animation clips play no part: a mesh with skin weights and bone indices passes without them. - iOS sends more resize events. On iOS,
window.WINDOW_EVENT_RESIZEDalso arrives after orientation transitions and safe-area inset changes, and, oncewindow.get_reserved_areashas been queried, when reserved areas change. A listener that assumes the size changed has to compare it with the last size.