Tips to port C2 addon to C3 addon (please add more!)

  • Other C2/C3 port authors, please post other tips or help me correct the below. chadorireborn, Eren macube, skymen

    C2C3 Addon Conversion

    Convert from C2 files to get C3 templates and file structure

    • Use the C2C3 converter to get aces.json, etc. lang files c3 runtime stubs (c2c3converter.exe -c3stubs ./In ./Out) For exact usage and details see: c2c3converter

    Convert ACE functions

    • Individually cut ACE functions from c2 runtime.js paste them to the stubs in the actions.js, conditions.js, expressions.js functions.
    • For expressions change the return values through the normal JS return function for C3 rather than ret object passed in c2 as a parameter to the expression function.
    • Change any c2 SDK functions used in the ACE functions to their C3 SDK counterparts, or change functionality to adapt to differences in the SDKs.
    • Look at the 'addon specific' code in the C2 runtime.js that is not in the ACE functions, including addon specific addon variables (made be defined at this.<addonvarable> 'scope',
    • Copy the addon specific code to the c3runtime/instance.js into the proper scope for the functions or variables.
    • I have put some functions into the instances constructor, but it depends on what functions call this code and the scope needed. I have had to change it around in the past (put some internal, some external, some with this.<blah> depending on the scope and what functions are calling what.)

    Testing and debugging

    • Use a local server (I used nodemon) and C3 developer mode to load addons and debug
    • In developer mode you do not have to pkg files up each time you change
    • Edit the files to fix bugs and reload the local server to refresh the addon, reload the C3 editor and project. for each addon change.

    Read and understand: C3 SDK Manual

  • official c3 plugins is very helpful in convert c2 plugins.

    the codes are minify. but still understandable.

    you can download the "save all resources" plugin from the Chrome Web Store for to download all c3 plugins.

    and you can write "c3_runtimeInterface._localRuntime" to the debug console for access the runtime. (type "c3runtime" for c2)

    In this way, you can search for c2 values ​​in c3.

  • Usually most of the undocumented runtime functions that you used still exist but are either named in PascalCase or have an additionnal underscore before them.

    For exemple this.inst.GetWorldInfo()._SetLayer()

    If a plugin has a huge class that does all of the heavy work (like rex's addons sometimes do) you can just copy paste the whole thing in plugin.js or behavior.js at the very top and expect it to work fine.

    If said class uses functions from C2 runtime, just replace them but it should be easy.

    In C3 runtime the "this" you're controlling is not an inst class but an sdkInst. So if you want to call a function from another plugin (like sprite) you must do


    This will also let you access any property defined there, like current animation, and any defined helper function.

    The easiest way to know what you can access is by using console.log on "this"

    It will print every property, and list all of the functions you have in the last property named "__proto__". Each function will be named, and will list the needed arguments.

    The minification scirra used for the runtime files is pretty basic. They just replaced every function and var names with a single letter. All the runtime function names and Exps, Acts, and Cnds names can't br altered though so they haven't been changed.

    It's a way different story for the editor sdk though.

    However, I'm pretty sure that since the editor is also JS you can console.log your way through everything as well.

    I think you can get every file C3 has if you managed to host C3 on a local server. I haven't done that myself, but I know it is possible, and will let you access the addon's editor code and commonAces files.

  • I must emphasise that if you look for features using the debugger, you will find undocumented features that are not supported and could break at any time. See this warning in the SDK documentation:

    The runtime APIs allow access to all parts of the engine. Do not use undocumented features, or other object's properties or methods beginning with an underscore, which is a convention used to indicate private features. These features are subject to change at any time, including backwards-incompatible changes, or complete removal, that may break your addon. If your addon uses these features and is broken by a change, we will not offer any support, since you should not have been using them in the first place. If users complain about the breakage, we will forward them on to you. It is important to allow flexibility in the core engine to ensure we can make optimisations, do necessary refactoring, implement new features, and so on, which is why we will only support the documented, public APIs.

  • Try Construct 3

    Develop games in your browser. Powerful, performant & highly capable.

    Try Now Construct 3 users don't see these ads
  • Also, to demonstrate the importance of this:

    For exemple this.inst.GetWorldInfo()._SetLayer()

    The reason _SetLayer() is marked private (via the underscore) and is undocumented, is because it is an internal engine call. It must be used simultaneously with a range of other calls across the engine, otherwise it will corrupt the internal state of the runtime and break the game. In other words, it's not useful on its own, and using it will break things. This is true of any other features you find that are undocumented.

    This has been a huge pain for us and other people before. Please do not go and write code using stuff like this.

  • I get that, but then it would be nice to either have documentation about the functions that allow us to do that.

    I know SetLayer isn't meant to be used on its own, I read through the commonAces file and reused that code.

    But then if I can't use it, how can I move an object accross layers?

    Do I need to create a SOL containing my one object instance and then call Action on that object type and SOL so it reuses the CommonACE file code? This is an issue I came accross when porting my skins addon which adds and syncs a skin on top of a sprite.

    But to do so, how can I create a SOL?

    For this simple case there are some issues. Not only the doc lacks content, but it also has false info in it. Like GetImagePoint(nameOrIndex) that states that it returns two values between 0 and 1, which it doesn't.

    Also when porting C2 addons that used undocumented features we can't really do anything but use those same features. The addon usually wouldn't use undocumented features if it didn't have to, and when porting it, we can either use them, or not port it at all.

    That's only accounting for the fact that the addon used undocumented features. But in the case of some plugins (like Spritefont+ and my Spritefont Deluxe) we can't even use what was documented in C2, like adding 3rd party files as a default texture.

  • Please request official features in the SDK - don't just go and dig up undocumented, unsupported features.

  • Alright, I dropped a few requests on the ideas platform.

    Still, it would be nice to have someone on the team dedicated to adding features to the SDK and documenting them at one point in the future.

Jump to:
Active Users
There are 1 visitors browsing this topic (0 users and 1 guests)