18 KiB
ADR 0013: ActionScript compatibility
- Status: accepted (2026-11-08) as scope and placement. Tier 1 built (2026-11-09, see "Tier 1 as built" below). Tier 2 built (2026-11-10, see "Tier 2 as built")
- Relates to: requirements U2 (scripting surface), roadmap M6, ADR 0009 (XFL import),
docs/legal/compliance.md
Context
The project lead asked for ActionScript on the roadmap if it fits our constraints, at low priority, since it serves a smaller group of users. U2 already settled AniCraft's own scripting: the Craft-family WebAssembly plug-ins, with frame scripts on the same sandbox. The ActionScript question is about compatibility for people who bring Animate projects with code in them.
What those users have, in order of how common it is:
- Timeline control in frame scripts:
stop(),play(),gotoAndPlay/gotoAndStopby frame number or label,nextFrame/prevFrame, the same calls on a named instance (hero_mc.gotoAndStop("run")), and button clicks wired to those calls withaddEventListener(MouseEvent.CLICK, …). Most animation and e-learning work only uses this. - Small logic: variables,
if, loops,trace, setting instance properties (x,alpha,visible), simple functions. - Applications and games: classes in packages, the document class, linked symbol classes,
the full
flash.*platform API (display list, events, networking, sound, text), compiled to bytecode for a player.
Current Animate documents run ActionScript 3.0 only; ActionScript 1 and 2 live only in old files. Today the XFL importer drops frame scripts without a word.
Our constraints: Rust only, no unsafe, never crash on hostile input, everything is a command,
time is a function (evaluate is pure), clean room (public documents and observation only),
permissive dependencies from crates.io, and Adobe names used only nominatively.
Decision
ActionScript fits as a compatibility front end in three tiers, built in order, each one useful alone. Only the first two are planned. It stays low priority: in M6 after the WebAssembly plug-ins, frame scripts and HTML canvas export, and it may slip past M8 without blocking anything else.
- Keep (tier 1). Scripts are content and are never lost.
- The document model gets
Keyframe.script: Option<Arc<Script>>, whereScriptholds the source text verbatim and its language (ActionScript3,ActionScript1or2,Other), plus symbol linkage and document class names as plain strings. Saved in.anicraft(a minor format version with#[serde(default)], so older files open unchanged). - The XFL importer reads
<Actionscript><script>on frames (scenes and symbols) and the linkage attributes. The import report counts them as kept, not run. As of this ADR it reports them as skipped; that line moves when tier 1 lands. - An Actions panel (the generic name, see Legal) shows and edits a keyframe's script
in a monospace editor with line numbers. Keyframes with a script get a small marker in
the timeline. Commands:
script.set,script.clear,script.list, so agents and the CLI can read and write scripts too. - Rendering and every export ignore scripts. Tier 1 runs nothing.
- The document model gets
- Run the timeline subset (tier 2). The common case from item 1, plus a little of item 2.
- New crate
anicraft-script(layer 0; it knows the language, not the document): a hand-written lexer and recursive-descent parser for an ActionScript 3 subset, with bounded nesting depth, source length and token count. It lowers what it accepts to a small, typed timeline action IR (stop, play, go to frame or label (optionally in a scene), next and previous frame or scene, target an instance by its name path, a button event handler for click, over, out, press and release,traceoutput, and a few instance properties). Anything outside the subset is reported with line and column; the script is kept and not run. Nothing is half-run. - The IR is the shared vocabulary. WebAssembly frame scripts (U2) call the host with the same actions, and the HTML canvas exporter writes the same actions out as JavaScript. One runtime, many front ends; ActionScript is not a second engine.
- Time stays a function. Scripts never change the document. Interactive playback is a
separate, pure player in
anicraft-doc:PlayerState(each timeline's playhead and playing flag) is stepped bystep(doc, &state, &events) -> stateand drawn by evaluating the document at that state. The authoring stage and every export stay script-free and deterministic; a Test Movie preview window and the HTML canvas export use the player. Fuel limits a step's work, so a bad loop can't hang the app. navigateToURLand other effects outside the movie are ignored in preview (reported in its output), so opening a file can't make AniCraft do things outside the document.
- New crate
- Not planned: the full language and platform (tier 3). Classes, packages, the
flash.*API, a bytecode virtual machine and SWF export with compiled code. That is a second product (a player), and open-source players for old content already exist. We revisit only if users ask for it. If we ever do, SWF export first: its specification is public (see compliance §4), and the tier-2 IR compiles down to it.
Why this fits the constraints
- Rust only, no unsafe, no new licences. Tiers 1 and 2 are our own code; tier 1 needs no dependency at all. No embedded JavaScript or Flash engine.
- Never crash. The parser is bounded and fuzzed with the other importers; the player is fuel-limited; unsupported code is reported, not guessed.
- Everything is a command (
script.*), so it works headless and over MCP. - Clean room. The language is learned from public documents: the ECMAScript 3rd edition
standard (ECMA-262) that ActionScript 3 builds on, Adobe's public ActionScript 3.0 language
and component reference and its "Learning ActionScript 3.0" guide, and observing what
self-authored files do. No Adobe code, SDKs, compilers or player internals. The XFL
<Actionscript>element comes from the same public format descriptions and self-authored files as the rest of ADR 0009. Sources get a row inATTRIBUTION.mdwhen the code lands. - Legal. "ActionScript" is an Adobe trademark. Docs and compatibility messages use it nominatively to say which language a script is written in (as import messages already name Animate). Feature names stay generic: the Actions panel, frame scripts, Test Movie. A programming language itself isn't protected by copyright; counsel review covers this together with XFL (compliance §7).
Consequences
- Animate users keep their code when they open their files, and simple interactive pieces (menus, "click to continue", looping characters with stops) play in preview and in HTML canvas exports without being rewritten.
- Documents with scripts look the same in every export as before, because exports render the authored timeline, not a played session. That matches Animate's own video export.
- Games and applications written in ActionScript don't run in AniCraft and won't in this plan. Their artwork and timelines still come across, and their scripts are kept.
- The subset is a moving line. It grows from user reports of the "not run" messages, never by guessing what unsupported code would have done.
Tier 1 as built (2026-11-09)
Tier 1 follows the decision above. Where the build refines it:
- Where scripts live. A kept script is a third variant of the frame-script enum ADR 0024
put on keyframes:
Keyframe.script: Option<FrameScript>withFrameScript::Source(Arc<SourceScript>)besideActionsandPlugin.SourceScript(inanicraft-actions, L0, so the tier-2 parser can read it) holdslanguage(actionscript3,actionscript1or2,other) andtext, byte for byte. A separate field would have allowed a keyframe to hold actions and a script, and then nobody could say which one runs once tier 2 lowers scripts to actions. One field keeps "one of them" true by construction. Setting actions on a keyframe with a script replaces it (undo restores it), as switching between actions and plug-ins already did. TheArcmeans copying a keyframe, taking an undo snapshot or handing the document to the render thread never copies the text. - Class names.
Symbol.linkage: Option<Linkage { class, base }>andDocument.document_class: String, as dotted identifiers (at most 256 characters). An older document'slinkageIdentifieris stored asclass. All of these fields are#[serde(default)]and are left out of the file when empty, so the format stays version 3, as it did for ADR 0024's fields, and older files open unchanged. - Limits and repair. A script is at most 1 MiB. Loading drops a script that is empty or too long whole, because cutting code would change it, and drops class names that aren't names. The XFL importer reports dropped scripts the same way.
- XFL.
<Actionscript><script>on frames in scenes and in every kind of symbol is kept (graphic and button timelines and guide layers too: nothing there runs, but it is content). Linkage comes fromlinkageClassName(elselinkageIdentifier) unlesslinkageExportForASturns it off, andlinkageBaseClassgives the base class. The language and the document class come from the publish profile (PublishSettings.xml, the profile marked current, itsActionScriptVersionandDocumentClass). When a file doesn't say, the language is ActionScript 3.0. A missing or unreadable profile changes nothing, because it holds settings, not content. These element names come from public descriptions of the format and are checked against self-authored files only, as the rest of ADR 0009 is. The report gains a kept, not run list next to "not yet supported" (counts of frame scripts by language, linkage classes and the document class). Scripts on instances (older documents'on (…)handlers) and linkage on bitmaps and sounds have no place yet and are reported as left out. - Commands.
script.set(textand/orlanguage; empty text clears),script.clear(kept scripts only, never actions),script.list(every kept script with its text, every linkage class and the document class) andscript.set_class(a symbol's linkage, or the document class). They reach any symbol's timeline and guide layers, whichactions.*can't (Scope::Keeps). Plug-in policy: command plug-ins may call all ofscript.*. Scripts are document content like actions and frame labels, which plug-ins already read and write (actions.*is allowed). Writing a script runs nothing, and when tier 2 runs scripts it does so in the pure, budgeted player, which can't reach outside the movie. Frame-script plug-ins still can't call commands at all. - App. The Actions panel's Frame tab gets a Type row (Actions, Plug-in, Script). Script
shows the language, the line count and the text in a monospace (
Type::Path) editor with line numbers. Typing edits the document live, and a burst of typing is one undo step. Tabs are typed into the code. Esc leaves the editor. A file's CR LF line ends show as one break, and the stored text is changed only by an edit. Symbols with kept scripts appear in the panel's timeline list whatever their kind. The timeline's "a" marker covers kept scripts. Properties shows the symbol's linkage Class and the document Class in documents that use scripts. A class field commits when it loses focus, because a half-typed name isn't a name yet. Test Movie says how many kept scripts don't run (once, not every time one passes), and the HTML canvas export lists them in its report. - Not in tier 1: scripts on instances, linkage on bitmaps and sounds, a document-wide default language, syntax colouring, and exporting scripts back to XFL.
Tier 2 as built (2026-11-10)
Tier 2 follows the decision above. Where the build refines it:
- Where the language lives: a module, not a crate. The parser is
anicraft_actions::as3(lex.rs,parse.rs,lower.rs), inside the L0 crate that holds the action IR, rather than a newanicraft-scriptcrate. Two reasons. The layering rule (src/architecture_tests.rs) lets a crate use only lower layers, so an L0anicraft-scriptcould not name the L0 IR it lowers to; ADR 0024 put the IR at L0 for exactly the front ends that lower to it. And a kept script's compiled form is a pure function of its text, so it is cached on the script itself:SourceScript::compiled()fills aOnceLockthe first time it is asked (never saved, never compared, emptied by a clone). The document shares scripts byArc, so undo snapshots, the render thread, Test Movie, the HTML export and the importer all reuse one compile. A separate crate would have needed a cache keyed outside the script, or a compile on every frame entered. The module knows the language and the IR only; the crate stays serde-only. - The subset.
stop(),play(),gotoAndPlay/gotoAndStop(a frame number, 1-based, or a label; optionally a scene),nextFrame(),prevFrame(),nextScene(),prevScene(); the same on instance-name paths (hero_mc.arm_mc.play(),this.parent,parent,root, the castsMovieClip(…),Object(…)and… as MovieClip);addEventListenerforMouseEvent.CLICK,MOUSE_DOWN,MOUSE_UP,ROLL_OVER/MOUSE_OVERandROLL_OUT/MOUSE_OUT(or their strings), with a function declared in the script or written in place, whose body is made of these calls;e.currentTargetin a listener is the instance listened to;traceof literals and of+ - * / %over them, joined and formatted as ActionScript does (Number.toString, ECMA-262 §9.8.1); settingx,y,alpha,visible,rotation,scaleX,scaleYto such values; a call to one of the script's own functions runs its body in place (no recursion; 16 deep at most).import, comments, missing semicolons (insertion as ECMA-262 §7.9), type annotations andreturn;read as the language does. - Never half-run. Lowering accepts only what the IR says exactly. Anything else (variables,
if, loops, reading a property,removeEventListener, other events, classes) is a problem with its line and column, and the whole script doesn't run. The parser reads more of the language than runs (statements and expressions in general, skipping loop headers andswitch/trybodies by balanced brackets), so the problem names the construct and where it is, and lowering lists every problem (up to 32), not just the first. A syntax error stops at the first. - Outside the movie.
navigateToURL,sendToURL,fscommandandExternalInterface.callare ignored and listed as notes; the script still runs.buttonModeanduseHandCursorare noted too (the pointer is already a hand over everything clickable). - Bounds. 256 KiB of source runs (the 1 MiB kept limit still holds), 65,536 tokens, nesting 64 deep (statements and expressions; deeper is a problem, never a stack overflow), 100,000 statements lowered counting inlined copies (calls that fan out), 256 steps per script and per listener, 64 listeners per script, 32 problems. The player's per-step budgets (ADR 0024) count each step as one action. A hostile-input test (token soup and raw bytes, 5,000 scripts) runs in well under a second; it must never panic. Measured (dev profile, this build's optimised debug): a typical frame script compiles in ~9 µs, a 200 KB one of 2,500 functions in ~11 ms, once per script.
- Listeners in the player. The IR gains no new action: a compiled script is a list of
ScriptOps, each anActionor aListen(a target, aButtonEvent, the function's name and its actions). Running aListenadds the listener toPlayerState.listenersunder the instance it names (buttons and movie clips; a graphic, the main timeline or a missing name is an Output line). Adding the same function for the same event again changes nothing, as in ActionScript (an inline function counts as one function, so a looping frame doesn't pile up copies). A listener lives while its instance and its script's timeline stay on the stage. On an event the instance's own handler (ADR 0024) runs first, then its listeners in the order added, each on its script's timeline. A movie clip with a listener can be clicked, as one with handlers can.nextScene()in a movie clip's own script writes an Output line instead of moving the main timeline (a clip has one scene in ActionScript); the Actions panel's Next scene action keeps its meaning. - Where it shows. Test Movie's Output starts with one line per kept script: "Frame script
runs: Scene 1 › Actions, frame 1", or "not run" with the first problem; the window counts
the scripts that don't run. The Actions panel's Script view says whether the script runs
(and how many steps it lowered to), lists the notes, or lists each problem with its line and
column above the code and marks those lines in the gutter; clicking a problem puts the
cursor there. The XFL import report lists frame scripts that run apart from those kept.
script.setandscript.listsayrunsandproblems;script.check {text, language?}compiles a text without storing it and returns its steps. The HTML canvas export writes the same steps forplayer.js, which mirrors the Rust player's listeners (tested step by step in Boa, state, output and display list alike); scripts outside the subset stay out of the page and are counted in its report. - Messages. Problems are engine messages, in English like the rest of the engine's
(
docs/localisation.md); the panel's frame around them is translated. - Not in tier 2 yet: variables and conditions, reading properties,
removeEventListener,Event.ENTER_FRAMEand keyboard events, functions declared on other frames of the timeline, event bubbling from a clip's children to its listeners,e.target,getChildByName, sound andstage, and ActionScript 1.0 and 2.0. Each is reported where it is, so the subset can grow from what users' files actually use.