@lost-c3/lib@3.3.2

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711
![Lost by lostinmind.](https://raw.githubusercontent.com/lostinmind-dev/lost-c3/refs/heads/master/cover.png)

<div align="center">
  <h3>
    Lost for easy making Construct 3 Addons. <br />
    v3.2.3
  </h3>
</div>

**Lost** is a framework for easy making Construct 3 addons using
**[Deno (JavaScript runtime)](https://deno.com)** that was created by
lostinmind.

## Navigation

<!-- - __[Examples](https://github.com/lostinmindd/lost-c3-examples)__ -->

- **[💪 Advantages](#-advantages)**
- **[🚀 Quickstart](#-quickstart)**
- **[🔌 Creating ***`Plugin`*** addon](#-creating-plugin-addon)**
- **[🎛️ Creating ***`Behavior`*** addon](#️-creating-behavior-addon)**
- **[🏗️ Building addon](#️-building-addon)**
- **[🧪 Testing addon](#-testing-addons-in-developer-mode)**

# 💪 Advantages

Here I've compiled some of the benefits from standard addon creation for
**Construct 3**.
> - ⚡️ **Using the powerful _**JavaScript Runtime**_ [Deno](https://deno.com).**
> - ❌ **Error detecting before installization of your Addon!**
> - 📝 **Only _**Typescript**_ and no _**Javascript**_ for your addon**
> - E **___Typescript___ support for addon scripts!**
> - 🚀 **Fast compilation to .c3addon format!**
> - 🧪 **Built-in addon testing using
>   [Developer Mode in Construct 3](https://www.construct.net/en/make-games/manuals/addon-sdk/guide/using-developer-mode)**.
> - 📂 **No need to configure separately _**aces.json**_ and _**en-US.json**_
>   files for addon. All necessary properties for _**aces.json**_ and
>   _**en-US.json**_ are defined together with the function implementation.**
> - 🔍 **There is no need to configure addon _.js_ scripts/files. _**Lost**_
>   automatically detects the addon scripts/files!**
> - 📜 **Structured categorization of all addon _**Actions, Conditions,
>   Expressions**_. Categories are separated files like _MyCategory.ts._**
> - 🚫 **Possibility to mark all _**Actions, Conditions, Expressions**_ in a
>   category as _Deprecated_ instead of having to configure each _**Action,
>   Condition, Expression**_ separately.**
> - ✨ **Additional tools to format the displayed text in Construct 3 itself by
>   using built-in functions - formatting the text into a specific BBCode tag.**

# 🚀 Quickstart

- **Install [Deno (JavaScript runtime)](https://docs.deno.com/runtime/)**
- **Install [Lost CLI](https://jsr.io/@lost-c3/lib) by using**
  `deno install --name lost jsr:@lost-c3/lib/cli --global -f -A`
- **Create empty folder which will be used as main folder for your addon.**

```bash
deno install --name lost jsr:@lost-c3/lib/cli --global -f -A
lost create
```
- **Create a bare-bones project for addon by using one of the following commands:**
```bash
lost create --plugin    # Creates a bare-bones project for 'Plugin' addon
```

```bash
lost create --drawing-plugin    # Creates a bare-bones project for 'Drawing Plugin' addon
```

```bash
lost create --behavior    # Creates a bare-bones project for 'Behavior' addon
```



>[!IMPORTANT] Check and install the latest version of Lost CLI!
> deno install --name lost jsr:@lost-c3/lib@LAST_VERSION/cli --global -f -A

# 📝 Documentation

## 🔌 Creating `Plugin` addon
```bash
lost create --plugin    # Creates a bare-bones project for 'plugin' addon
```

### 🧱 File structure
```bash
├── Addon/                      # Addon runtime classes folder
│   ├── Categories/             # Categories folder
│   ├── DomSide/                # Addon DOM side scripts folder
│   ├── Files/                  # Addon files folder
│   ├── Scripts/                # Addon scripts folder
│   ├── Modules/                # Addon modules folder
│   ├── Types/                  # Addon scripts folder
│       └── global.d.ts         # Declaration file for your purposes
│   ├── icon.svg                # Your .svg OR .png addon icon
│   ├── Instance.ts             # Addon runtime Instance class
│   ├── Plugin.ts               # Addon runtime Plugin class
│   └── Type.ts                 # Addon runtime Type class
├── Builds/                     # Builds folder
│   ├── Source/                 # Final Construct 3 addon folder
│       └── ...
│   └── AddonId_Version.c3addon # Final .c3addon file
├── Editor/                     # Builds folder
│   ├── Instance.ts             # Editor Instance class
│   └── Type.ts                 # Editor Type class
├── deno.json                   # deno.json file for Deno enviroment
├── addon.ts                    # Main addon file
├── lost.config.ts              # Addon config file
```

### ⚙️ Config setup
Let's setup _`lost.config.ts`_ config file at first.

```typescript
import { defineConfig } from "jsr:@lost-c3/lib";

export default defineConfig<'plugin'>({
    /**
     * Set addon type
     */
    type: 'plugin',
    /**
     * Set plugin type
     */
    pluginType: 'object' | 'world',
    /**
     * Set a boolean of whether the addon is deprecated or not.
     */
    deprecated?: false,

    /**
     * A boolean indicating whether the addon supports Construct's worker mode, where the entire runtime is hosted in a Web Worker instead of the main thread.
     */
    supportsWorkerMode?: false,
    /**
     * The minimum Construct version required to load your addon, e.g. "r399".
     */
    minConstructVersion?: 'r416', 
    /**
     * Pass false to prevent the addon from being bundled via the Bundle addons project property.
     */
    canBeBundled?: false,
    /**
     * Pass true to set the plugin to be a single-global type.
     */
    isSingleGlobal?: true,

    /**
     * An object name that will applied after plugin was installed/added to project.
     */
    objectName: 'LostPluginName',

    addonId: 'Lost_MyAddon',
    addonName: 'Lost addon for Construct 3',
    addonDescription: 'Amazing addon made with Lost.',
    category: 'general',
    version: '1.0.0.0',
    author: 'lostinmind.',
    websiteUrl: `https://addon.com`,
    docsUrl: `https://docs.addon.com`,
    helpUrl: {
        EN: 'https://myaddon.com/help/en'
    }
})
```

### ⚙️ Addon setup
Let's setup _`addon.ts`_ file at second.

```typescript
import { defineAddon, Plugin, Property } from 'jsr:@lost-c3/lib';
import type { EditorInstance } from "@Editor/Instance.ts";
import type { EditorType } from "@Editor/Type.ts";
import config from "./lost.config.ts";

export default defineAddon(
    new Plugin<EditorInstance, EditorType>(config)
        .addFilesToOutput()

        .setRuntimeScripts()

        .addRemoteScripts('https://cdn/index.js')

        /** @Properties  */
        .addProperty('integer', 'Integer', { type: Property.Integer })
        .addProperty('float', 'Float', { type: Property.Float })
        .addProperty('percent', 'Percent', { type: Property.Percent })
        .addProperty('text', 'Text', { type: Property.Text })
        .addProperty('longText', 'Long Text', { type: Property.LongText })
        .addProperty('check', 'Check', { type: Property.Checkbox })
        .addProperty('font', 'Font', { type: Property.Font })
        .addProperty('combo', 'Combo', {
            type: Property.Combo,
            items: [['item1', 'item2']]
        })
        .addProperty('color', 'Color', { type: Property.Color, initialValue: [255, 210, 155] })
        .createGroup('group', 'Awesome Group')
            .addProperty('info', 'Info', {
                type: Property.Info,
                callback: (inst) => {
                    return '';
                }
            })
            .addProperty('link', 'Link', {
                type: Property.Link,
                linkText: 'Do ...',
                callbackType: 'for-each-instance',
                callback: (inst) => {
                    console.log('Link property for each instance');
                }
            })
            .addProperty('link2', 'Link', {
                type: Property.Link,
                linkText: 'Do ...',
                callbackType: 'once-for-type',
                callback: (type) => {
                    console.log('Link property once for type');
                }
            })
)
```

### 📁 Creating category
To create category you should create new **`CategoryName.ts`** file in path:
`./Addon/Categories` folder. Then you can use code snippet from bare-bones
project **`!cc`** to create default Category structure or copy-paste below
script.

```typescript
import { Category, Action, Condition, Expression, addParam } from "jsr:@lost-c3/lib";
import type { Instance } from "../Instance.ts";

@Category('myCategory', 'Category Name', { isDeprecated: false, inDevelopment: false })
export default class {
    /** @Actions */

    /** @Conditions */

    /** @Expressions */
}
```

>[!INFO] *isDeprecated* property in options for category in @Category decorator deprecates all category Actions, Conditions, Expressions.

>[!WARNING] *inDevelopment* property in options for category in @Category decorator removes all category Actions, Conditions, Expressions from addon.

#### ⚡️ Create action

To create actions for your addon you should use _`@Action`_ method decorator
in your category class.

Example

```typescript
import { Category, Action, Condition, Expression } from 'jsr:@lost-c3/lib';
import type { Instance } from '../Instance.ts';

/**
 * Setup your category settings here
 */
@Category('categoryId', 'Category Name')
export default class MyCategory {
    @Action(
        /**
         * A string specifying a unique ID for the ACE.
         */
        `doSomething`,
        /**
         * The name that appears in the action picker dialog.
         */
        `Do something`,
        /**
         * The text that appears in the event sheet. 
         * You can use simple BBCode tags like [b] and [i], and use {0}, {1} etc. as parameter placeholders.
         * For easy BBCode import functions from @lost-c3/lib --> Bold, Italic, Underline, Strikethrough, Code
         */
        `Do something`,
        /**
         * A description of the action or condition, which appears as a tip at the top of the condition/action picker dialog.
         */
        `Awesome description...`,
        {
            /**
             * Set to true to mark the action as asynchronous. 
             */
            isAsync: false,
            /**
             * Set to true to deprecate.
             */
            isDeprecated: false,
            /*
             * Set to true to highlight.
             */
            highlight: true,
            /**
             * Setup your parameters here.
             */
            params: []
        }
    )
    doSomething() {
        console.log('Do something');
    };    
}
```

> [!TIP]
> You can use build-in [BBCode](#-fast-bbcode-features) functions for fast and
> beautiful development.

#### ❓ Create condition

To create conditions for your addon you should use _`@Condition`_ method
decorator in your category class.

Example

```typescript
import { Category, Action, Condition, Expression } from 'jsr:@lost-c3/lib';
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Condition(
        `onEvent`,
        `On event`,
        `On event`,
        'Trigger when something done...',
        {
            /**
             * Specifies a trigger condition.
             */
            isTrigger: true,
            /**
             * Allow the condition to be used in the same branch as a trigger.
             */
            isCompatibleWithTriggers: false,
            /**
             * Specifies a fake trigger.
             */
            isFakeTrigger: false,
            /**
             * Allow the condition to be inverted in the event sheet.
             */
            isInvertible: false,
            /**
             * Display an icon in the event sheet to indicate the condition loops.
             */
            isLooping: false,
            /**
             * Normally, the condition runtime method is executed once per picked instance.
             */
            isStatic: false,
            isDeprecated: false,
            highlight: false,
            params: []
        }
    )
    onEvent(this: Instance) { return true };
}
```

> [!TIP]
> You can use build-in [BBCode](#-fast-bbcode-features) functions for fast and
> beautiful development.

#### 🧮 Create expression

To create expressions for your addon you should use _`@Expression`_ decorator in
your category class.

Example

```typescript
import { Category, Action, Condition, Expression } from 'jsr:@lost-c3/lib';
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Expression(
        `getValue`,
        `GetValue`,
        `Returns some value`,
        {
            /**
             *  "number" OR "string" OR "any".
             */
            returnType: 'string',
            /**
             * Allow the user to enter any number of parameters beyond those defined.
             */
            isVariadicParameters: false,
            isDeprecated: false,
            highlight: false,
            params: []
        }
    )
    getValue(this: Instance) { return 'value' };
}
```

> [!TIP]
> You can use build-in [BBCode](#-fast-bbcode-features) functions for fast and
> beautiful development.

#### 🔧 Setting up Action/Condition/Expression parameters

To setup parameters in your Action/Condition/Expression you should use 'params'
field when you creating on of the entity. Also you should use `addParam()` method AND `Param` enum that you can import from library.

**List of available parameter types:**

| Type | Description |
| ----------- | ----------- |
| ```"Number"``` | **A number parameter.** |
| ```"String"``` | **A string parameter.** |
| ```"Any"``` | **Either a number or a string.** |
| ```"Boolean"``` | **A boolean parameter, displayed as a checkbox.** |
| ```"Combo"``` | **A dropdown list.** |
| ```"Cmp"``` | **A dropdown list with comparison options like "equal to", "less than" etc.** |
| ```"Object"``` | **An object picker.** |
| ```"ObjectName"``` | **A string parameter which is interpreted as an object name.** |
| ```"Layer"``` | **A string parameter which is interpreted as a layer name.** |
| ```"Layout"``` | **A dropdown list with every layout in the project.** |
| ```"Keyb"``` | **A keyboard key picker.** |
| ```"InstanceVar"``` | **A dropdown list with the non-boolean instance variables the object has.** |
| ```"InstanceVarBool"``` | **A dropdown list with the boolean instance variables the object has.** |
| ```"EventVar"``` | **A dropdown list with non-boolean event variables in scope.** |
| ```"EventVarBool"``` | **A dropdown list with boolean event variables in scope.** |
| ```"Animation"``` | **A string parameter which is interpreted as an animation name in the object.** |
| ```"ObjInstanceVar"``` | **A dropdown list with non-boolean instance variables available in a prior "object" parameter.** |

*Example*

```typescript
import { Category, Action, Condition, Expression, addParam, Param } from 'jsr:@lost-c3/lib';
import { bold } from 'jsr:@lost-c3/lib/misc';
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Action({
        `doActionWithParams`,
        `Do action`,
        `Do action with value: ${Bold('{0}')}`,
        {
            params: [
                addParam('value', 'Value', { type: Param.String, initialValue?: '' })
            ]
        }
    })
    doActionWithParams(this: Instance, value: string) {
        console.log('Do action with value', value);
    };
}
```

#### 💢 Deprecating _Actions_, _Conditions_, _Expressions_

> [!CAUTION]
> Do not delete any actions, conditions, expressions from your category file.
> Because it can break projects that are using your addon inside.
>
> Read more info:
> https://www.construct.net/en/make-games/manuals/addon-sdk/guide/defining-aces#internalH1Link0

How to mark any Action, Condition OR Expression as deprecated? Each Action,
Condition OR Expression has _isDeprecated_ property in decorator options property, so you can set
it to _`true`_ to deprecate.

Example

```typescript
import { Action, Category, Condition, Expression } from 'jsr:@lost-c3/lib';
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Action(`doAction`, `Do action`, `Do action`, {
        /**
         * Default is False. Set to true to deprecate the ACE.
         */
        isDeprecated: true
    })
    doActionWithParams() { /* do something */ }
}
```

### 🌳 Using Instance
Use Instance class to implement your custom logic to addon. Main instance file
is available at path: `./Addon/Instance.ts`.

Example of using Instance properties and functions inside any category entity
(Action/Condition/Expression).

_Instance.ts_

```typescript
class LostInstance extends globalThis.ISDKInstanceBase {
    readonly value: string = 'My property value';
    /**
     * Use this property to call any condition in your addon
     */
    readonly Conditions = C3.Plugins[Lost.addonId].Cnds;

    constructor() {
        super();
        const properties = this._getInitProperties();

        if (properties) {
            /**
             * Here you can find your plugin properties
             */
        }
    }

    _release() {
        super
            ._release();
    }

    /**
     * Here is our instance method
     */
    _getPropertyValue() {
        return this.value;
    }
}

export type { LostInstance as Instance };
```

_MyCategory.ts_

```typescript
import { Action, Category, Condition, Expression } from 'jsr:@lost-c3/lib';
/**
 * Import your instance type
 */
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Expression(`getValue`, `GetValue`)
    /**
     * Set the first argument of your method to: this: Instance
     */
    GetValue(this: Instance) {
        return this._getPropertyValue();
    }
}
```

### 📚 Using Scripts (Javascript / Typescript)
It's available to use custom **Javascript** OR **Typescript** script in your addon.

To use any script you should copy OR create _**script.js**_ OR _**script.ts**_ file at path:
`./Addon/Scripts`. Your script will automatically will be loaded with type:
**external-dom-script**.


- To use any file you should copy your _**file.css**_ OR _**data.txt**_ file to
  path: `./Addon/Files`. If you added any **.css** file it will automatically
  loaded with type: _**external-css**_. If you added file with any other
  extension it will automatically loaded with type: _**copy-to-output**_.

> [!NOTE]
> All **Typescript** files will be compiled into .js files after addon building.

> [!NOTE]
> If you want to load your script with type **external-runtime-script**, you
> should call `setRuntimeScripts(path)` in your Addon object in _**`addon.ts`**_ file.

*Example*

```typescript
import { Plugin, Property } from 'jsr:@lost-c3/lib';
import type { EditorInstance } from "@Editor/Instance.ts";
import type { EditorType } from "@Editor/Type.ts";
import config from "./lost.config.ts";

export default defineAddon(
    new Plugin<EditorInstance, EditorType>(config)
        .setRuntimeScripts('myscript1.ts', 'main/myscript.ts')
)
```

### 📄 Using Files
It's available to use files in your addon.

To use any file you should copy OR create _**file.***_ file at path:
`./Addon/Files`. Your file will automatically will be loaded with auto-detected type.

> [!NOTE]
> If you want to include your file in project build, you should call `addFilesToOutput(path)` in your Addon object in _**`addon.ts`**_ file.

*Example*

```typescript
import { Plugin, Property } from 'jsr:@lost-c3/lib';
import type { EditorInstance } from "@Editor/Instance.ts";
import type { EditorType } from "@Editor/Type.ts";
import config from "./lost.config.ts";

export default defineAddon(
    new Plugin<EditorInstance, EditorType>(config)
        .addFilesToOutput('myfile.wasm')
)
```

### 📦 Using Modules
It's available to use custom **Javascript** OR **Typescript** module in your addon.

To use any module you should copy OR create _**mymodule.js**_ file at path:
`./Addon/Modules`.

*Example*

```typescript
import * as MyModule from './Modules/mymodule.ts';

class LostInstance extends globalThis.ISDKInstanceBase {

	readonly PluginConditions = C3.Plugins[Lost.addonId].Cnds;
	constructor() {
		super();
		const properties = this._getInitProperties();

		console.log(MyModule.VAR);

        if (properties) {

        }

	}

	_release() {
		super._release();
	}

};

export type { LostInstance as Instance };
```

> [!NOTE]
> All **Typescript** files will be compiled into .js files after addon building.

>[!WARNING] Note this is only supported from r401+.

>[!INFO] 📖 For more info checkout official docs:
>
>https://www.construct.net/en/make-games/manuals/addon-sdk/guide/runtime-scripts/sdk-v2

### 🔤 Fast BBCode features
For *fast* and *beautiful* development there is a few functions that can help you
customize displaying text in your addon.

**List of available BBCode functions:**

| Function | Result |
| ----------- | ----------- |
| ```bold('Do action')``` | **Do action** |
| ```italic('Do action')``` | *Do action* |
| ```strikethrough('Do action')``` | ~~Do action~~ |
| ```underline('Do action')``` | <u>Do action</u> |
| ```code('Do action')``` | <code>Do action</code> |

*Example*

```typescript
import { bold, code, italic, strikethrough, underline } from 'jsr:@lost-c3/lib/misc';
import { Action, Category } from 'jsr:@lost-c3/lib';
import type { Instance } from '../Instance.ts';

@Category('categoryId', 'Category Name')
export default class {
    @Action(
        `doAction`,
        `${bold('Action name')}`,
        `${italic('Do something')} and ${strikethrough('NOT')}`,
        `${underline('Underlined description...')} with ${code('SOMETHING')}`
    )
    doAction(this: Instance) { /* do something */}
}
```

## 🏗️ Building addon

To build addon into **`.c3addon`** file you can use one of the following
commands:

- `lost build`

**`addon.c3addon`** file will be available at path: `./Builds/my_addon_1.0.0.0.c3addon`

## 🧪 Testing addons in Developer Mode

To test your addon you can use one of the following commands:

- `lost serve`

> [!IMPORTANT]
> Read more info about Developer Mode in Construct 3:
>
> https://www.construct.net/en/make-games/manuals/addon-sdk/guide/using-developer-mode


# 🪪 License

MIT