Skip to content

Latest commit

 

History

History
170 lines (140 loc) · 8.35 KB

Config.md

File metadata and controls

170 lines (140 loc) · 8.35 KB

Config reference

ax4 expects exactly one argument: path to a JSON config file.

java -jar converter.jar config.json

Required fields

Key Type Description
src string or string[] AS3 source root(s).
hxout string Output directory for generated Haxe.
swc string[] SWC files loaded as extern/type sources.

Optional fields

Key Type Default Description
skipFiles string[] null Exact file paths to skip during source walk.
packagePartRenames { [name: string]: string } null Package segment rename map after normalization.
injection object null Configuration used by metadata rewrite filter.
haxeTypes { [path: string]: string } null Type/signature overrides for SWC declarations.
rootImports string null File whose content is appended to generated import.hx.
settings object { flashProperties: "none" } Filter-specific switches.
keepTypes bool false Keep explicit type hints that could be inferred.
dataout string hxout Output directory for non-AS files copied from src.
dataext string[] null Optional extension allow-list (without dot, example: ["png","xml"]).
datafiles string[] null Optional explicit file allow-list plus explicit extra files to copy.
copyNonAs bool true Copy non-AS files discovered under src during walk.
unpackout string null Directory where library.swf extracted from SWCs is written.
unpackswc string[] null SWC files to unpack into unpackout.
hxoutClean bool false Delete hxout contents before conversion.
dataoutClean bool false Delete dataout contents before conversion (only when dataout is explicitly set).
formatter bool false Run haxelib run formatter -s <hxout> after generation.
testCloneExpr bool false Internal diagnostic switch for clone-expression smoke checks.
copy { unit: string, to: string }[] null Copy files/directories before conversion.

settings fields

Key Type Default Description
checkNullIteratee bool false Adds ASCompat.checkNullIteratee(...) guards in rewritten for...in/for each.
haxeRobotlegs bool false Enables Robotlegs-specific typing behavior.
flashProperties "none" | "externInterface" | "all" "none" Controls @:flash.property metadata generation.

injection object

Key Type Required if injection is set Description
magicInterface string Yes Fully-qualified interface path.
magicBaseClasses string[] Yes Base classes/interfaces exempted from auto-implement injection.

Example:

{
  "injection": {
    "magicInterface": "my.di.ITypeAware",
    "magicBaseClasses": [
      "my.di.BaseMediator",
      "my.di.BaseCommand"
    ]
  }
}

Non-AS copy behavior

The converter walks src recursively:

  • .as files are parsed and converted.
  • Non-AS files are copied according to the rules below.

Rules:

  1. Target directory is dataout when provided, otherwise hxout.
  2. copyNonAs = false disables copy of non-AS files discovered under src.
  3. When copyNonAs = true:
    • If neither dataext nor datafiles is provided: all non-AS files from src are copied.
    • If dataext and/or datafiles is provided: only matching files are copied.
  4. datafiles entries are always copied explicitly to the same target directory.
  5. Relative paths are preserved for files inside src.

dataoutClean note:

  • dataoutClean only applies when dataout is explicitly configured.
  • If dataout is omitted, non-AS files go to hxout and cleanup is controlled by hxoutClean.

haxeTypes format

haxeTypes keys target SWC declarations:

  • Class field: package.Class.field
  • Getter override: package.Class.field$get
  • Setter override: package.Class.field$set
  • Constructor override: package.Class.new

Values are parsed as either:

  • Type hint: "Array<Int>", "my.pkg.CustomType", "Dictionary<String, Dynamic>"
  • Signature override: "p1:Int|p2:String|return:Bool"

Example:

{
  "haxeTypes": {
    "flash.display.DisplayObject.filters$get": "return:Array<flash.filters.BitmapFilter>",
    "flash.display.DisplayObject.filters$set": "p1:Array<flash.filters.BitmapFilter>"
  }
}

Path and platform notes

  • Prefer forward slashes (/) in config paths on all platforms.
  • skipFiles must match the walked file path exactly.
  • unpackout and unpackswc must be used together.
  • For copy, directory entries are copied recursively; file entries expect to as a full destination file path.

Full example

{
  "src": [
    "project/src",
    "project/generated"
  ],
  "hxout": "out/hx",
  "swc": [
    "lib/playerglobal32_0.swc",
    "lib/FRESteamWorks.swc"
  ],
  "skipFiles": [
    "project/src/legacy/DoNotConvert.as"
  ],
  "packagePartRenames": {
    "floor": "floorpkg"
  },
  "settings": {
    "checkNullIteratee": true,
    "haxeRobotlegs": false,
    "flashProperties": "externInterface"
  },
  "haxeTypes": {
    "flash.display.DisplayObject.filters$get": "return:Array<flash.filters.BitmapFilter>",
    "flash.display.DisplayObject.filters$set": "p1:Array<flash.filters.BitmapFilter>"
  },
  "rootImports": "config/root-imports.hx",
  "keepTypes": true,
  "copy": [
    { "unit": "compat", "to": "out/compat" }
  ],
  "copyNonAs": true,
  "dataout": "out/data",
  "dataext": ["xml", "png", "json"],
  "datafiles": [
    "config/game-config.json"
  ],
  "hxoutClean": true,
  "dataoutClean": true,
  "formatter": true,
  "unpackout": "out/unpacked",
  "unpackswc": [
    "lib/playerglobal32_0.swc"
  ]
}