AS3PB

AS3PB is a Protocol Buffers code generator and runtime for ActionScript 3, designed for compact wire payloads and low-allocation game/runtime use.

The repository contains:

• protoc-gen-as3, the protoc plugin that emits AS3 message, enum, and RPC client code.
• as3-protoc, a small wrapper for invoking protoc with the AS3 generator.
• runtime/, the AS3 runtime support library used by generated code.
• examples/, a small generated example schema.
• runtime/test/, runtime fixtures, tests, benchmark, and RPC sample.

Requirements

For generator usage:

• Go
• protoc

For local development and runtime builds:

• Just
• AIR SDK with mxmlc and compc on PATH

The AIR SDK can be downloaded with:

just download-air-sdk

You can also pass an OS explicitly:

just download-air-sdk linux
just download-air-sdk mac
just download-air-sdk windows

After downloading, add the SDK bin directory to PATH before building AS3 targets.

Install

Install the generator and protoc wrapper with Go:

go install github.com/33TU/as3pb/cmd/protoc-gen-as3@latest
go install github.com/33TU/as3pb/cmd/as3-protoc@latest

For local development, build them into bin/:

just build-protoc-gen-as3
just build-as3-protoc

Generate AS3

The easiest way to generate AS3 code is as3-protoc. It invokes protoc, configures protoc-gen-as3, and adds proto import mappings for you:

as3-protoc -I proto --as3_out=generated proto/game.proto

When using local development binaries:

bin/as3-protoc \
  --protoc_gen_as3_bin=bin/protoc-gen-as3 \
  -I examples/proto \
  --as3_out=examples/generated \
  examples/proto/game.proto

You can also invoke protoc-gen-as3 directly through protoc:

protoc \
  --plugin=protoc-gen-as3=protoc-gen-as3 \
  --as3_opt=Mgame.proto=as3.pb \
  --as3_out=generated \
  -I proto \
  proto/game.proto

Direct protoc usage requires imported proto files to have usable Go package metadata or explicit Mfile.proto=package mappings. The as3-protoc wrapper adds those mappings automatically by scanning include paths.

Generator options can be passed with --as3_opt:

as3-protoc \
  -I proto \
  --as3_out=generated \
  --as3_opt=generate_any=true \
  --as3_opt=generate_serialize=true \
  --as3_opt=generate_deserialize=true \
  proto/game.proto

Available options:

• debug: print generator debug logs.
• generate_always: generate files even when protoc did not mark them for generation.
• indent: set the generated indentation string. Defaults to four spaces.
• inline_reset: emit [Inline] on generated reset methods. Defaults to true.
• generate_any: emit message type URLs and automatic AnyRegistry registration. Defaults to true.
• generate_serialize: emit serializeBytes methods. Defaults to true.
• generate_deserialize: emit deserializeBytes methods. Defaults to true.

The same options can be set with environment variables:

• AS3PB_DEBUG
• AS3PB_GENERATE_ALWAYS
• AS3PB_INDENT
• AS3PB_INLINE_RESET
• AS3PB_GENERATE_ANY
• AS3PB_GENERATE_SERIALIZE
• AS3PB_GENERATE_DESERIALIZE

Use The Runtime

Generated AS3 code depends on the runtime package in runtime/src/as3pb.

For performance-sensitive projects, copy or vendor runtime/src/as3pb into your AS3 project and compile it together with your generated code. This lets the AS3 compiler see runtime [Inline] methods while compiling the final SWF.

Example layout:

src/
generated/
vendor/as3pb/

Example compile source paths:

mxmlc \
  -source-path src \
  -source-path generated \
  -source-path vendor \
  src/Main.as

You can also build the runtime as a SWC:

just build-swc

Using the runtime source is recommended for game/runtime builds where inlining and allocation behavior matter. The SWC is convenient for packaging, IDE setup, or projects that prefer binary library dependencies.

Commands

List available recipes:

just

Run Go tests:

just test

Build the Go tools and AS3 runtime SWC:

just build

Build individual Go tools:

just build-protoc-gen-as3
just build-as3-protoc

Build the runtime SWC:

just build-swc

Runtime Tests And Samples

Generate AS3 runtime fixture code:

just generate-runtime-test-data

Build the runtime test SWF:

just build-runtime-test

Build the benchmark SWF:

just build-runtime-bench

Example Flash Player result for the included benchmark fixture:

Messages: 100
Iterations: 300

Protocol Buffers avg: 285 bytes/message
JSON avg: 718 bytes/message
AMF3 avg: 593 bytes/message
JSON/Proto size ratio: 2.52x
AMF3/Proto size ratio: 2.09x

Protocol Buffers serialize: 85ms
JSON serialize: 1608ms
AMF3 serialize: 197ms
JSON/Proto serialize ratio: 18.92x
AMF3/Proto serialize ratio: 2.32x

Protocol Buffers deserialize: 35ms
JSON deserialize: 283ms
AMF3 deserialize: 374ms
JSON/Proto deserialize ratio: 8.09x
AMF3/Proto deserialize ratio: 10.69x

Protocol Buffers total: 120ms
JSON total: 1891ms
AMF3 total: 571ms
JSON/Proto total ratio: 15.76x
AMF3/Proto total ratio: 4.76x

Build the RPC sample SWF:

just build-runtime-rpc

Run the Go RPC fixture server used by the RPC sample:

just run-runtime-rpc-server

The RPC server is a nested Go module in runtime/test/rpc-server. Its Go protobuf and Connect stubs are generated from runtime/test/data/rpc.proto with:

just generate-runtime-rpc-server

Examples

Regenerate example AS3 output:

just generate-examples

Build the examples SWC:

just build-examples