Movatterモバイル変換

[0]ホーム
URL:

Construct for TypeScript developers quick start guide

UpvoteUpvote6DownvoteDownvote

Features on these Courses

    Stats

    640 visits, 851 views

    Tools

    Share

    • TwitterTwitter
    • FacebookFacebook
    • RedditReddit
    • VKVK
    • LinkedInLinkedIn

    Translations

    This tutorial hasn't been translated.

    License

    This tutorial is licensed underCC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

    Published on 10 Jun, 2025.

    Construct supports writing TypeScript code in both script files and event sheets. If you are new to the JavaScript programming language, consider looking for a beginner tutorial. However if you already have some knowledge of TypeScript coding, this guide will help you quickly get up to speed with TypeScript in Construct.

    JavaScript

    If you are interested in using JavaScript in Construct, see the separate guideConstruct for JavaScript developers quick start guide.

    Compiling TypeScript

    When writing TypeScript in Construct, it will be compiled to JavaScript using Construct's built-in TypeScript compiler. You don't need to add any .js files to your project - you only need to add a .ts file and the compilation to JavaScript happens automatically.

    If you want to use an external code editor like VS Code, the workflow is different - for details on that seeUsing an external editor in the manual.

    Modules

    All TypeScript code in Construct runs in modules, based on the language-provided module system, also known asES Modules orESM. Construct does not currently directly support other module patterns like CommonJS or AMD.

    Modules allow for using theimport andexport syntax, which is supported in Construct.

    The main script

    In Construct themain script is automatically loaded. This file appears bold in the Project Bar and has itsPurpose property set toMain script. However other scripts are not automatically loaded by default - instead they must be imported in order to load and execute them.

    Top-level scope

    If you've not worked with modules before, note thattop-level scope works differently in modules. Each module (script file) has its own top-level scope. This means top-level declarations are not globally accessible. Using imports and exports are preferable to global variables, but if you have to, useglobalThis to access the global namespace, as demonstrated below.

    // In a module, this is scoped only to the same file.let myGlobal = 0;// In a module, this is now global.globalThis.myGlobal = 0;

    Note that TypeScript does not normally allow using undeclared global variables. To allow this, add a TypeScript definition file (with extension .d.ts) to your project, and add a line like this:

    declare var myGlobal: number;

    This will then allow use of the global variable viaglobalThis.

    Importing third-party scripts

    Third-party scripts written in the modern ES Modules style should work normally in Construct. If you can, use a script based on ES Modules, or ask the third-party developer to provide one.

    If you import an older third-party JavaScript file that does not use ES Modules, it may try to add something to the global namespace by using a top-level declaration. Since modules have their own scope, this means the script won't actually declare anything usable in other script files. These scripts have to be lightly modified to get them to work as modules. Some further advice and examples on modifying JavaScript files is in theConstruct for JavaScript developers quick start guide.

    You can import JavaScript files and import them to TypeScript files. This kind of interoperability relies on TypeScript's support for interoperability with JavaScript. You may need to provide additional type definition files (.d.ts) when doing this. You can import .d.ts files to your Construct project and it will use the definitions for type checking without outputting anything when you export your project.

    Scripts in event sheets

    When adding TypeScript code in an event sheet, it actually runs inside an async function. This allows use ofawait in such code snippets. The event system can then wait for a previous block of code to finish using theWait for previous actions to complete system action.

    Note that since these code snippets are inside functions, the use ofimport andexport is not allowed, as these are not permitted inside functions. Further, any variable or function declarations will only be available in that snippet. Global variables can still be accessed usingglobalThis.

    Referring to script files in event sheets

    Scripts in event sheets are a concept unique to Construct. Therefore the way modules are accessed in scripts in event sheets is slightly different to the way script files work.

    Scripts in event sheets are all combined in to a single script file. If a script in the project has the purposeImports for events, its content is inserted to the top of that combined script file. This provides a way to use modules in scripts in event sheets.

    For example suppose theImports for events script uses the following import:

    import * from "./mymodule.js" as MyModule;

    This then means all scripts in event sheets in the entire project can now refer toMyModule.

    In fact theImports for events script can declare variables and functions that can then be used in scripts in event sheets. However usually it is preferable to import a script, as that can also be shared with other script files.

    TheImports for events script can also import the main script. This provides a convenient way to call functions exported from the main script from event sheets.

    import * from "./main.js" as Main;

    Construct APIs

    Construct provides a range of APIs to access Construct-specific features. These are typically accessed viaruntime, which refers to theruntime script interface, and has the typeIRuntime.

    In scripts in event sheets,runtime is automatically defined and so can be used directly.

    In script files,runtime is passed to a callback in the special Construct-providedrunOnStartup global function. The default code snippet in a newly added script file demonstrates using that. From there on, it is up to your own code to passruntime to code that needs to use it.

    Note thatrunOnStartup runs while the loading screen is showing, and so not all Construct features are ready to use yet. The "beforeprojectstart" event fires just before actually starting the first layout, which sometimes is the right place to put initialisation code.

    Construct objects are typically accessed viaruntime.objects, e.g.runtime.objects.Sprite is anIObjectClass representing the Sprite object.

    For example if there is only one instance of Sprite, then it can be retrieved usinggetFirstInstance() like so:

    const inst = runtime.objects.Sprite.getFirstInstance()!;// now can use inst.x, inst.y etc.

    Note the use of the! operator (non-null assertion). This is becausegetFirstInstance() may returnnull when there are no instances of the object. Therefore its return type allows returningnull. TypeScript will mark unconditional access of something that might benull as an error; using the! operator tells TypeScript that you know it definitely isn't null, and so suppresses any such errors.

    If there are multiple instances they can be iterated with methods such asinstances() like so:

    for (const inst of runtime.objects.Sprite.instances()){// now can use inst.x, inst.y etc.}

    The specific APIs for instances depends on the plugin type. These interfaces are all documented in the scripting reference section of the manual, such asISpriteInstance for Sprite instances, which provides APIs for things like animations. Note that these interfaces also inherit fromIWorldInstance andIInstance (depending on the kind of plugin). For example common properties likex andy are part ofIWorldInstance.

    Construct further generates a type definition for every object type in the project, such asInstanceType.Player for a Sprite object namedPlayer. This will derive fromISpriteInstance but add type definitions for the instance variables, behaviors and effects specific to that object type, ensuring they are autocompleted and type checked correctly. When writing TypeScript code you may wish to use a specific type likeInstanceType.Player if you want to refer to a specific object type, or a more general type likeISpriteInstance orIWorldInstance depending on whether that code is more generally applicable.

    Integrating scripts and events

    Strings and numbers can be exchanged between event sheets and TypeScript code using global and local variables in event sheets. Local variables are accessible vialocalVars inside scripts in event sheets, and global variables are accessible viaruntime.globalVars. There is more information in the manual section onScripts in event sheets.

    Strings and numbers can also be exchanged via instance variables via theinstVars property ofIInstance. (As noted previously Construct generates type definitions for each kind of object type which will include all the available instance variables.)

    See also the example projectIntegrating events with script for an example of some useful techniques.

    Using an external editor

    Construct has special features to let you use an external code editor like VS Code to write your project's code if you prefer. Note that the workflow is different to working within the Construct editor itself, and involves exporting your project's type definitions. See the guideUsing an external editor.

    Learn more

    Here are some more resources to learn more about using TypeScript in Construct.

    Examples

    There are lots of example projects using TypeScript coding in Construct which you can find in theScripting category in theExample Browser.

    Debugging

    You can still use the browser developer tools to debug code that you write in Construct. Note that the debugger will show the compiled JavaScript output of your TypeScript code, but that generally looks the same but just without the type annotations. For a quick-start guide on debugging, see the manual section onDebugging script.

    Minifying

    Minifying on export also applies to your TypeScript code written in Construct. When minifying, your TypeScript code is first compiled to JavaScript, and then the minification performed on the resulting JavaScript. Code minification is done with the industry-standard libraryterser.Simple minify mode should never affect how your code runs. However if you enableAdvanced minify mode on export, you may need to adjust how you write your code. See the manual guide onExporting with Advanced minification for more details.

    Worker mode

    Construct is capable of running its entire engine in a Web Worker, rendering via OffscreenCanvas. However by default projects using TypeScript code run in the main page ("DOM mode") to ensure compatibility with code that expects to be able to use DOM features likedocument. If your TypeScript code is compatible with running in a Web Worker, you can re-enable worker mode for improved performance by changing the project propertyUse worker toYes (in theAdvanced section). When you do this, Construct will also adjust the provided type definitions to match a worker context, so accessing DOM-specific APIs likedocument will be marked as an error. There is more information about this in the manual sectionJavaScript in Construct.

    Reference

    See theScripting section of the manual for full documentation on using TypeScript in Construct.

    • 1 Comments

    • Order by
    Want to leave a comment?Login orRegister an account!

    • Absurd. When you find that all AI models are extremely confusing all things up and down the SDK/js in C3, you will understand that it is no wonder that the development of C3 is like a marginal person, and there are a lot of complicated things, plus improper business models. Is this story about to enter a low tide? It's a waste of time to make some TypeScript that no one needs at all. Some people may need it. There are only three kittens who need it. There is lot of really a need we can see on community and many people repeat the need, but you don't do it. LOL

    [leaderboard-score]
      [8]ページ先頭
      ©2009-2025 Movatter.jp