Ashley's Forum Posts

    We had a warning in the SDK documentation saying "don't use undocumented features, they can change, break or be removed at any time". Addon developers largely ignored that warning, and hence the difficult situation we're in. People ignore warnings. We're not going to try relying on warnings again given it already failed so spectacularly.

    You forgot to answer one big point, why isn't the warning for addons made with SDK 1 enough ?

    Because unless we remove it, people will just carry on using it, and the disasters will still happen.

    Why wait for a hypothetical disaster later when we can enjoy a catastrophe right now

    It's not hypothetical. Disasters have happened, are happening, and will continue to get worse.

    For post length reasons I'll try and answer a few other questions here:

    Will Scirra provide assistance to help with porting from V1 to V2, besides the very simple SDK examples?

    There will definitely be a "porting v1 addons to v2" guide in the documentation. I've also already created commits on the GitHub repository showing diffs so you can see what was changed to go from v1 to v2.

    Is there a possibility to make a 'wrapper' around V2 SDK to support previous V1 SDK addons or at least for the vast majority of the V1 SDK?

    For simpler addons, porting mainly involves renaming things (e.g. see here). Perhaps some tool could be made to convert the basic template, but I think the APIs are too different to allow for full automatic conversion of arbitrary code.

    My hope is that is because the scripting interfaces for addons will be 'automatically' generated somehow.

    The addon SDK v2 classes are the script interfaces (they actually derive from the script interface classes), so there is no extra work to add a script interface.

    Construct has built in vectors, and a built in color class that handles all the math and conversion, yet if an addon needs these, your force to rewrite all that code?

    Anything we expose to addon developers must be supported permanently and with backwards compatibility, otherwise we end up with the same problem of customer projects being ruined. So we can't say 'here, have access to this library of vector/math/utility code' - we have to design a public API that will be supported forever. That's a lot of work and a significant long-term maintenance consideration, and can take away our flexibility to do something like an engine optimization by changing the library code. Instead the approach we have taken with the script APIs is to use the browser built-in features such as DOMRect instead of a custom rectangle class. Want more? Import a JavaScript library. Problem solved, and no risk of compatibility disaster.

    The solutions are far from ideal, sure, but with addon SDK v2, the alternatives become far worse, and IMO, would lead to way bigger issues down the line.

    The downside of accessing engine internals is ruining customer's projects. This can be so bad, in the long run it is in my view significantly worse than any of the other options. I guess you haven't had to deal with desperate customers begging you to fix their ruined project and been unable to help? We definitely have. In my professional opinion: literally any other solution is better than modifying the engine internals. Hacking the engine internals carries such a severe risk of disaster that it must be ruled out, which is why the software industry invented encapsulation and has been using it widely for decades. In other tools with a proper API with encapsulation, people get by with workarounds or alternatives, and while that may be painful and difficult sometimes, it's a better option.

    Part of this project is over the next year or so to make sure the v2 addon SDK has sufficient APIs that it can cover necessary features, or just add new built-in features instead so there doesn't need to be an addon. We do want to minimize the disruption and make sure there is as smooth a transition as can be achieved. However, please, please don't try to bypass the encapsulation, or start copy-pasting chunks of the engine. Please, please, please please please please don't do that. I pretty much have trauma from how utterly awful the consequences of that were with C2. It is just a total, epic disaster, for us and our customers. Please please please please please don't do that. And it is the risk of that kind of epic disaster we are trying to put an end to with the addon SDK v2.

    Folks, please remember the goal here is to stop a regular occurence of customer projects being ruined by permanently broken and unmaintained addons. I don't think addon developers always see the consequence of this, so perhaps it is harder to understand. But from time to time we get desperate emails from customers who have projects they've been working on for years begging us for help, when the problem is they use some addon that is now permanently broken. Unfortunately we usually cannot help them, and it really pains me to see that happening to customers. This has happened a bunch of times in the past, it's happened recently, and it's going to continue happening. I genuinely fear that a few years from now there will be some huge compatibility disaster and thousands of projects are permanently broken, or we have to retract some major improvement and cancel plans for further improvements - a catastrophe either way. If that did happen I'm sure everyone would be saying how our top priority is to better design our software to prevent that happening. I think the main reason we have avoided that so far is luck, and I don't expect our luck to last forever. We're trying to solve this problem before such a disaster happens, and to stop the regular occurence of ruined projects.

    The addon SDK v2 solves this by using proper encapsulation. That's the industry standard approach. Literally all other software already uses that approach. Nobody allows unfettered access to engine internals through installable addons, because everyone in the industry knows that's a disaster waiting to happen. Access to source code is different to this: we are talking about the long-term compatibility of installable addons written by third-party developers, not just whether you can download the entire engine source code.

    I am largely just re-stating the same case here, and I don't really want to have to keep re-stating it over and over. I am fully aware of the extent of disruption and extra work this is going to cause. This is regrettable. However consider that we are not doing this for fun. We could just carry on as we were before - but in my professional opinion the problem is so serious that it does warrant this disruption. We have a responsibility to take tough decisions to do the right thing for the product and for customers.

    it looks like you plan to break every single addon ever made for C3

    It is unfortunate that all addons need updating. But we already went through this with moving from C2 to C3, where all addons needed rewriting, and then again with moving from the C2 runtime to the C3 runtime, where all addon runtime scripts needed rewriting again. I know this creates a lot of work and I don't like doing it, but I strongly believe it is necessary to avoid compatibility disasters, as the current approach is not sustainable.

    So are those promises not worth anything anymore ?

    All the documented APIs in the addon SDK v1 are supported in the addon SDK v2. So they are still supported, but addon developers need to move to the new SDK to continue using them.

    But this SDK change would be more like "if you can't do this events, and if you can't do this as an addon, then either change your vision for your game, or submit a suggestion and wait X months/years to maybe see it accepted or rejected".

    This is how it works in every other engine, because you generally can't access the internal engine in any other software. It was only really possible in Construct because of JavaScript's weak encapsulation. In other engines, people use workarounds or other approaches. You should do that in Construct too - in fact that's what people should have done in the first place, instead of resorting to accessing internal details of the engine, which causes compatibility disasters.

    Last updated: 19th November 2024

    In Construct 3 r391 (released 14th May 2024), we introduced a new addon SDK, which changes the way plugin and behavior runtime scripts are written. This post outlines why we need to do this and how the roll-out of the SDK v2 and phase-out of the SDK v1 will work.

    Unmaintainability of existing SDK

    Construct's original addon SDK is not sustainable. Plugins and behaviors can access internal details of the runtime, mainly because the JavaScript programming language has historically had weak encapsulation features. Despite our SDK documentation warning not to do this, a number of addons have been published that do this anyway. While accessing internal details might seem like a good option to get things done in the short term, in the long term it causes disaster, ending up ruining customer's projects as addons permanently break. This is because in the long run, all internal details of the engine eventually are changed, replaced or upgraded, and this usually breaks addons that access internal details; the changes may then be impossible to reimplement as the internal details have fundamentally changed, or it may simply be that years later the original developer is no longer around and so won't update it. In the long run this harm can outweigh any good the addon did in the first place. This problem is already occuring, with the latest Construct update breaking a few addons, it has already been a severe problem in the past, and it will likely only get worse with time.

    Introducing SDK v2

    We aim to solve this problem and ensure customer's projects can continue working even in the long term without maintenance by the addon developer. We're doing this by introducing a new and redesigned addon SDK v2. This uses encapsulation to ensure addons only use a long-term supported API, which is the industry-standard approach, including with most other game development tools. Ultimately we will retire the addon SDK v1, but phasing it out will be a long process. This is to allow addon developers time to migrate, as well as co-operating with addon developers to ensure the SDK v2 covers all features where reasonable and feasible. However developers should be aware some internal features they were using may not have an API created for them, as we do not want those features to be accessed by outside developers, as it is not maintainable to do so; in this case, unfortunately the addon developer must carry the responsibility for ignoring the warning in our SDK documentation, and they will have to retire their addon and customers will have to move to alternative features or workarounds. We will do our best to avoid such cases wherever possible, but the warning in the SDK documentation was there for a reason, and these addons were likely to end up permanently broken in the long run anyway.

    SDK v2 design

    Construct already has a broad, long-term supported JavaScript API in its JavaScript coding feature. This was introduced in 2019 and was specially designed with modern encapsulation features to ensure it is robust in the long term and avoid the same maintenance problems that plague the addon SDK v1. Rather than creating a separate API, the addon SDK v2 is implemented in terms of the existing JavaScript APIs, unifying both the addon SDK and the scripting feature, so code is written the same way for both.

    This approach has several key benefits, including:

    • Adding a new API makes it available to both the scripting feature and addon SDK at the same time, making it quicker to improve both. This also avoids the problem of the documented SDK methods lagging behind the script API features (such as with access to collision APIs in the past).
    • In the long run, new API improvements for the SDK will make the scripting feature more powerful, and vice versa. There have already been some API additions for the SDK v2 that benefit the scripting feature.
    • The API only needs to be documented once, rather than having two sets of API documentation for runtime methods.
    • As addons are implemented directly on scripting classes, there is no need for a separate script interface class - the addon class is the script interface.
    • It allows for writing addons with TypeScript, similar to how TypeScript can be used to write code in projects.
    • People already familiar with Construct's JavaScript coding feature will find it much easier to develop addons, and vice versa.

    Note that this only affects runtime scripts for plugins and behaviors. Effects and themes have no changes with the SDK v2. Editor scripts and JSON files for plugins and behaviors have only very minor changes, and DOM scripts and wrapper extensions do not need any modification at all.

    Getting started with the SDK v2

    The following resources are available to help addon developers write new addons using the Addon SDK v2, or port existing addons to the Addon SDK v2.

    SDK samples

    All the sample plugins and behaviors in the addon SDK have been ported to the SDK v2. There is also a new 'basic bullet' sample behavior with the SDK v2. You can find these on the Construct Addon SDK GitHub repository, under behavior-sdk/v2 and plugin-sdk/v2. You can also see in the commit list a set of commits to update each sample plugin and behavior to the addon SDK v2, such as this commit for updating the singleGlobalPlugin sample. These show diffs that highlight exactly what needs to be changed to update an addon.

    Documentation reference

    The Addon SDK documentation now covers the Addon SDK v2. A full reference on the APIs specific to the Addon SDK v2 is now available in the Addon SDK interfaces section of Construct's scripting reference.

    Porting guide

    The Addon SDK documentation now includes a guide on Porting to the Addon SDK v2 to help addon developers upgrade existing addons to SDK v2.

    Publishing

    Construct has had support for the Addon SDK v2 since Construct 3 r391, a beta release that came out in May 2024. The first stable release with support for SDK v2 addons was r397 (June 2024). Ported addons can now be published and can support all Construct versions r397+.

    In the Addons section of the website, there is a checkbox labelled Uses Addon SDK v2 when editing an addon. If you distribute your addon here and have updated it to use SDK v2, be sure to check this box; this then ensures it is listed when using the SDKv2 addons only filtering option, which will eventually be enabled by default and therefore hide all old addons using SDK v1 by default unless this option has been checked.

    New features in the Addon SDK v2

    As part of our work introducing the new addon SDK, we've done a range of upgrades and added support for new features. These include:

    • Full TypeScript support for addon development, covering both editor and runtime scripts - see TypeScript support in the Addon SDK documentation
    • SDK v2 addons can now be installed by dragging and dropping the .c3addon to the main Construct window
    • Set a minimum supported Construct version for addons
    • Editor type and instance scripts, and runtime plugin and type scripts, are now optional, which can help make it simpler and easier to develop addons
    • Autocomplete for tag parameters (via "autocompleteId" option for string parameters)
    • A new drawMesh() method for flexible 2D/3D rendering
    • Addons can be set to not support worker mode to force any projects using them to run in DOM mode (although supporting worker mode is strongly recommended where possible)
    • Access to HTML layers to insert custom HTML content (including custom canvas elements, e.g. to insert a 3D engine canvas in between Construct layers)

    Roll-out timeline

    Replacing an SDK is a complex project, and also requires addon developers update all their addons, and then all customers install the updated addons. We realize this is potentially a lot of work for addon developers. Unfortunately this is a necessary part of the project, but we are providing a long period of time before the phase-out of the old SDK to allow plenty of time for this work to take place.

    The timeline is subject to change, but we are guaranteeing at least the following time periods before any action is taken - so if it changes it will only be to delay steps on this timeline.

    • Milestone 1: beta release of the addon SDK v2 (in r391 on 14th May 2024).
    • Milestone 2 (we are here): stable release of the addon SDK v2 and all documentation complete (in r397 on 24th June 2024).
    • Milestone 3: Construct will start showing compatibility warnings when opening a project that uses SDK v1 addons, prompting the user to update them, or contact the addon developer for an update. This will be at least 6 months after milestone 2 (not before December 24th 2024).
    • Milestone 4: Construct will remove support for SDK v1 addons. The addons will no longer be loaded in the editor, and projects using them will fail to open and report that the addons are not supported and need updating. This will be at least 6 months after milestone 3 (and so at least 12 months after milestone 2, not before June 24th 2025).

    LTS release

    Further to the above timeline, we are planning a Long Term Support (LTS) release to further extend support for SDK v1 addons. The last stable release of Construct to support SDK v1 (just before Milestone 4) will be made an LTS release and supported with essential fixes and updates only for another 18 months.

    Therefore addon developers have, as a minimum, over a year to update their addons (from May 2024 to to June 2025) to support new versions of Construct until Milestone 4. Further, customers will be able to continue using a supported version of Construct with SDK v1 addons for a period of at least two and a half years (from May 2024 to the end of 2026), as there will be an LTS release at Milestone 4 to extend support by another 18 months.

    We will review this schedule over time and milestones may be delayed if necessary, but we are publishing this as a guide for addon developers to plan with on the assumption that this schedule will be adhered to.

    Conclusion

    Construct will ultimately drop support for the Addon SDK v1, so addon developers should now be actively updating their plugins and behaviors to use the Addon SDK v2 and publishing these updates. We realise this could be a significant amount of work for some developers, but we strongly believe this is a necessary step to provide customers confidence that their projects will continue to work in the long term. Improving customer's trust in third-party addons should also encourage adoption of third-party addons, as there will be less cause for customers to avoid them entirely for fear of compatibility problems. Finally, we believe the SDK v2 is better designed and easier to maintain, and by unifying the addon SDK and scripting features, will allow both to be improved much more quickly than otherwise. We ask for addon developer's patience and co-operation as we go through this process.

    Tagged:

  • Try Construct 3

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

    Try Now Construct 3 users don't see these ads

  • It's not currently supported (the way picking works with custom actions doesn't map straightforwardly on to a function call in code), but you can probably do it indirectly by calling a normal function which then calls a custom action.

  • Please direct your complaints to AMD, whose software is the one that is broken. Or try one of the other things I said - you haven't commented on whether WebGL or WebGPU renderers affect this, and they may well do. If you don't try my suggestions then it is not possible for me to help any further. Please see also the Forum & Community guidelines. If you continue to blame us when it's not our software that is broken, and you don't co-operate with my suggestions, then the thread will be locked.

  • I would advise to do what I previously said:

    Try to get in touch with AMD if you can, otherwise try filing an issue with Google to see if they can help. Maybe also turning on/off WebGPU mode will help avoid the issue.

  • It looks like the rendering problem occurs when the value of the "Compositing Mode" parameter is set to "Standard".

    That setting has been removed in the latest beta because, ironically, it actually tends to cause more bugs when set to "low latency".

    Graphics driver bugs are a nightmare to deal with. Try to get in touch with AMD if you can, otherwise try filing an issue with Google to see if they can help. Maybe also turning on/off WebGPU mode will help avoid the issue.

  • It's by design: they work the same as Array and Dictionary, which is that you can put them in a container with another object to have per-instance state. So just like you can put an Array in a container with a Sprite to have per-instance array data, you can put a Flowchart Controller in a container with a Sprite to have per-instance flowchart state.

  • You do not have permission to view this post

  • But at the same time I don't want to take a risk and turn it on forcibly

    If it used to be on, then changing the setting to force it to be on just means it's doing the same thing it was before.

  • The worker mode "auto" means Construct decides automatically, and we sometimes tweak the way Construct decides to work around things like known issues. You can change the setting in Project Properties to either "yes" or "no" to indicate a specific setting, but you then might run in to some kind of problem that "auto" mode was trying to avoid.

  • It might be over the upload size limit. Try uploading a smaller file.