@scaffscript/core 0.1.3 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Undervolta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,329 +1,59 @@
 # ScaffScript
 
-A superset language of **GameMaker Language** (GML) for creating module-based GameMaker source codes. This minimal language is mainly used for developing GML libraries, but can also be used for other purposes.
+![ScaffScript Banner](./assets/Banner/banner1-4-1.webp)
 
-> [!WARNING]
-> This project is still in early development. The syntax and features are subject to change. Use at your own risk.
-
-## Key Features
-
-- Unify multiple source files into a single source file.
-- TypeScript-like syntax and module system.
-- Flexible configuration options.
-- Dev-friendly CLI interface.
-- Togglable integration (auto/manual) to your GameMaker project.
-- And more... (WIP)
-
-## Installation
-
-1. Install [Bun](https://bun.sh) (if not already installed).
-2. Clone this repository.
-3. Install dependencies:
-
-```bash
-bun install
-```
-
-4. CLI usage:
-
-```bash
-scaff <command> [args]
-```
-
-## Usage
-
-Use `*.ss` files to mark a file as a Scaff file. Normal `*.gml` files are still supported, but they are not processed by Scaff.
-
-### Export Module
-
-1. Use `export` statement to export types (a variable, function, class, interface, type, enum, or arrow function) from a Scaff file. 
-
-```js
-// my_file.ss
-
-export var my_var = 1;
-export let my_let = 2;						// `let` will be removed, so it'll become an instance variable
-export const MY_CONST = "Hello, World!";	// `const` will be converted to `#macro`
-
-export function my_func() {
-	show_debug_message("Hello, World!");
-}
-
-// arrow functions will be converted to function expression or method
-export const my_method = (name: string, age: number) => {
-	show_debug_message(`Hello, ${name}! You are ${age} years old.`);
-}
-
-export enum MY_ENUM {
-	A,
-	B,
-	C
-}
-
-// classes will be converted to struct constructor
-export class MyClass {						
-	constructor(name: string, age: number)
-
-	name: string = "";
-	age: number = 0;
-
-	show_name() {
-		show_debug_message(this.name);
-	}
-}
-
-// interfaces and types will be converted to struct
-export interface MyInterface {
-	name: string;
-	age: number = 0;				// default value is allowed, which not allowed in TypeScript
-	isActive?: boolean;				// optional property is allowed
-}
-
-// interfaces can be extended
-export interface MyExtInterface extends MyInterface {
-	address: string;
-}
-
-export type MyType = {
-	name: string = "";				// default value is allowed, which not allowed in TypeScript
-	age: number;
-	isActive?: boolean;				// optional property is allowed
-}
-
-// types intersection is allowed
-export type MyIntersectedType = MyType & {
-	address: string;
-}
-```
-
-You can do a barrel export (`export * from "<path>"`) as well, so that you can import modules from the parent directory:
-
-```js
-// index.ss
-
-export * from "my_file";			// export all types from "my_file"
-```
-
-2. Use `impl` statement to add implementation to a class.
-
-```js
-// my_file.ss
-
-export class MyClass {
-	constructor(name: string, age?: number)
+A minimal superset language of **GameMaker Language** (GML) for creating module-based GameMaker source codes. This minimal language is mainly used for developing GML libraries, but can also be used for other purposes.
 
-	name: string = "";
-	age: number = 0;
-}
-
-impl MyClass {
-	show_age() {
-		show_debug_message(age);
-	}
-}
-```
-
-You can split the implementation into multiple files as well:
-
-```js
-// set.ss
-
-impl MyClass {
-	set_age(age: number) {
-		age = age;
-	}
-
-	// static method
-	static static_method = (name: string) => {
-		show_debug_message($"Hello, {name}!");
-	}
-}
-```
-
-### Import Module
-
-1. Use `include` statement to import a module from another Scaff file, and replace the import statement with the actual content of the exported types.
-
-```js
-// my_other_file.ss
-
-include { my_var, my_func, MyClass } from "my_file"
-
-/**
- * The generated source code will replace the include statement with the actual content of the exported types.
- * 
- * For example, the above include statement will be replaced with:
-
- var my_var = 1;
- function my_func() {
- 	show_debug_message("Hello, World!");
- }
- function MyClass(name, age) constructor {
- 	// ...
- }
-
- */
-
-// non-included lines will be left as is
-show_debug_message("This line will be left as is.");
-
-// you can include multiple modules in a single file
-include my_enum from "my_file"
-/**
- enum MY_ENUM {
-  	A,
-  	B,
-  	C
- }
- */
-
- // you can include normal GML files as well
- include { "some_script.gml", "another_gml" } from "./scripts"	
- // must be in curly braces and double quotes, the order of the files will be preserved, the `.gml` extension is optional
-```
-
-2. Use `import` statement to import a module from another Scaff file, and then use `@<keyword>` statements to load and replace the content of a Scaff file to certain places in the code.
-
-| Keyword | Description | Example |
-| --- | --- | --- |
-| `@content` | Replace the statement with the actual content of the exported type. | `@content my_var` -> `var my_var = 1;` |
-| `@nameof` | Replace the statement with the **name** of the exported type. | `@nameof my_var` -> `"my_var"` |
-| `@valueof` or `@:` | Replace the statement with the **value** of the exported type. | `@valueof my_var` -> `1`, `@:my_var` -> `1` |
-| `@typeof` | Replace the statement with the **type** of the exported type. | `@typeof my_var` -> `"number"` |
-| `@use` | Replace the statement with the object shape of the exported type. Only works with `interface` or `type`. | `var obj = @use MyInterface { name: "John" }` -> `var obj = { name: "John", age: 0, isActive: false };` |
-
-```js
-// my_import.ss
-
-import { my_var } from "my_file"
-
-show_debug_message(@valueof my_var);	// 1
-show_debug_message(@:my_var);			// 1
-show_debug_message(@typeof my_var);		// "number"
-show_debug_message(@nameof my_var);		// "my_var"
-show_debug_message(@content my_var);	// var my_var = 1;
-```
-
-```js
-// my_other_file.ss
-
-import * from "my_file"
-
-my_method = function() {
-	@content my_var;					// replace with `var my_var = 1;`
-	var hello = @valueof MY_CONST;		// replace with `var hello = "Hello, World!";`
-	var obj = @use MyInterface { 		// replace with `var obj = { name: "John", age: 0, isActive: false };`
-		name: "John" 
-	};
-	
-	show_debug_message(my_var);			// 1
-	show_debug_message(obj.name);		// John
-
-	var inst = new MyClass("John", 20);	
-	inst.show_age();					// 20
-}
-```
+> [!CAUTION]
+> ScaffScript is **not** affiliated with or endorsed by YoYo Games Ltd. GameMaker and GML are trademarks of YoYo Games Ltd. 
 
 > [!WARNING]
-> If you use any of the `@` statements without importing the module first, the statement will be left as is, which won't be processed by Scaff, and won't be accepted by GameMaker. Even so, there are some exceptions for non-module `@` statements. Check the special `@` statements below (WIP).
-
-| Keyword | Description | Example |
-| --- | --- | --- |
-| `@now` | Replace the statement with the current timestamp in ISO 8601 format. | `var now = "@now";` -> `var now = "2021-01-01T00:00:00.000Z";` |
-| `@today` | Replace the statement with the current date in ISO 8601 format. | `var today = "@today";` -> `var today = "2021-01-01";` |
-| `@version` | Replace the statement with the current version of Scaff. | `var version = "@version";` -> `var version = "0.1.0";` |
-| `@file` | Replace the statement with the current file name. | `var file = "@file";` -> `var file = "my_file";` |
-| `@line` | Replace the statement with the current line number. | `var line = @line;` -> `var line = 1;` |
-| `@counter` | Replace the statement with an increasing number. | `var counter = @counter;` -> `var counter = 1;`, `var counter = @counter;` -> `var counter = 2;`, etc. |
-
-
-### GameMaker Integration
-
-Use `intg` statement to mark this file as an integration target, and `#[<name_or_event>]` statement to mark a block of code as a write target. The content of the file will be written to the actual GameMaker project.
-
-```js
-// my_file.ss
-
-intg { main, some_mod } to "./scripts/my_script"				// integrate to `scripts/my_script/my_script.gml`
+> This project is still in early development. The syntax and features are subject to change. Use at your own risk.
 
-#[main]
-show_debug_message("Hello, from my_script!");
+---
 
-#[some_mod]
-show_debug_message("Hello, from my_script (some_mod)!");
+## Key Features
 
-#[some_mod -- prod]
-show_debug_message("Hello, only in production!");
-```
+- **TypeScript-like Module System**. Use `export`, `import`, and `include` to organize code across `.ss` files, fully resolved at compile-time.
+- **Class Syntax**. Define classes with constructors, properties, and methods that compile to GML struct constructors. Extend classes across files with `impl`.
+- **Content Directives**. Inline compiled GML content (`@content`, `@valueof`, `@:`, etc.) directives for dynamic code insertion.
+- **Special Values**. Access compile-time tokens like `@now`, `@today`, `@version`, `@file`, and `@line` for metadata and debugging.
+- **Code Generation Blocks**. Use `#[blockName]` to define named content sections and `intg` to map them to GameMaker asset paths.
+- **GameMaker Integration**. Automatically writes `.gml` files, generates `.yy` metadata, and updates your `.yyp` project file for scripts and objects.
+- **File Scanning & Processing**. Recursive scanning of `.ss` and `.gml` files with dependency-aware processing order.
 
-```js
-// my_other_file.ss
+---
 
-intg * to "objects/my_object"		// integrate to `objects/my_object/*`
-intg { Step, keydown:keyboard_d } to "objects/my_other_object"	
+## Installation & Documentation
 
-// method 1
-#[main as create]					// integrate to `objects/my_object/Create_0.gml`
-show_debug_message("Hello, from my_object create event!");
+For more information, please refer to the official [documentation](https://scaffscript.lefinitas.com).
 
-// method 2
-#[StepEvent]						// <event_name>Event is also supported				
-show_debug_message("Hello, from my_object step event!");
+---
 
-// method 3
-#[key as KeyPress:KEYBOARD_ENTER]	// use `:` to specify the event number KEYBOARD_ENTER in this case)
-show_debug_message("Hello, from my_object keypress - enter event!");
+## Questions & Feature Requests
 
-// method 4
-#[keydown:keyboard_d event]			// the `event`, event type, and event number are case insensitive, add `event` suffix to mark as event (like in method 2 example)
-show_debug_message("Hello, from my_object keydown - d event!");
-```
+Feel free to start a [discussion](https://github.com/undervolta/scaffscript/discussions) or open an [issue](https://github.com/undervolta/scaffscript/issues) for any questions or feature requests.
 
-> [!NOTE]
-> If you're using method 2 or 4, the `event` keyword is required to mark the block as an event. 
-> The `event` keyword will be omitted in the block name, so `#[StepEvent]` will become `Step` in the integration block (example: `intg { Step } to "objects/my_object"`, notice no `Event` suffix).
-> If you're creating (not modifying) a new **collision** event, you need to specify the name of the other object (case sensitive, exact name of the object in the IDE, such as `obj_player`). And you need to reopen the IDE if you're creating a new collision event using Scaff integration.
+---
 
-### Configuration
+## Contributing
 
-Create a `scaff.config.<ts\|mjs\|cjs|json>` file in the root of your project with the following content:
+Contributions are welcome! Please open an issue or submit a pull request.
 
-```ts
-// scaff.config.ts
+1. Fork the [repository](https://github.com/undervolta/scaffscript).
+2. Clone the forked repository to your local machine.
+3. Make and test your changes.
+4. Commit your changes and push it to your forked repository.
+5. Open a pull request to the main repository.
 
-export default {
-	// ...
-};
-```
+---
 
-```js
-// scaff.config.mjs
+## Support
 
-export default {
-	// ...
-};
-```
+If you like this project, or this project helped you in any way, please consider supporting me on [Ko-fi](https://ko-fi.com/undervolta) or [Trakteer](https://trakteer.id/undervolta). Don't forget to leave a star! Your support is greatly appreciated!
 
-```js
-// scaff.config.cjs
+---
 
-module.exports = {
-	// ...
-};
-```
+## License
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `acceptAllIntegrations` | `boolean` | `false` | Accept all generated files to be integrated without manual confirmation. |
-| `clearOutputDir` | `boolean` | `false` | Clear the output directory before generating source code. |
-| `counterStart` | `number` | `1` | Starting value for the counter special value. |
-| `debugLevel` | `0 \| 1 \| 2` | `0` | Debug level. `0` = no debug, `1` = basic debug, `2` = verbose debug. |
-| `integrationOption` | `ScaffIntegrationOptions` | `{}` | Integration options. |
-| `noBackup` | `boolean` | `false` | Don't backup the original files before integration. |
-| `noIntegration` | `boolean` | `false` | Don't integrate the files to GM project. |
-| `onNotFound` | `"error" \| "ignore"` | `"error"` | What to do when something is not found. |
-| `path` | `Record<string, string>` | `{}` | Path aliases. |
-| `production` | `boolean` | `false` | Whether the script is running in production mode. |
-| `tabType` | `"1t" \| "2s" \| "4s"` | `"1t"` | Tab type to use when generating source code. |
-| `targetPlatform` | `ScaffIntegrationTargetPlatform` | `"all"` | Target platform for the generated code. |
-| `useGmAssetPath` | `boolean` | `false` | Whether to use GM asset path when integrating files. |
+ScaffScript is **free** and **open-source**. It's licensed under the [MIT License](./LICENSE).

package/dist/index.cjs

@@ -115,12 +115,7 @@ async function parseArgs(...args) {
         log.error("No source path specified. Please specify a valid source path. Aborting...");
         return null;
       }
-      const target = args[2];
-      if (target !== "to") {
-        log.error(`Invalid target: \x1B[33m${target}\x1B[0m. Please replace it with \x1B[32mto\x1B[0m after the source path argument. Aborting...`);
-        return null;
-      }
-      const yypPath = args[3];
+      const yypPath = args[2];
       if (!yypPath) {
         log.error("No project path specified. Please specify a valid project path. Aborting...");
         return null;
@@ -146,39 +141,15 @@ async function parseArgs(...args) {
       console.log(`\x1B[34m[args]\x1B[0m:     Optional arguments.`);
       console.log("");
       console.log("Commands:");
-      console.log("  gen(erate) <source_path> to <project_path>  Generate source code from the given path to the given project");
-      console.log("  help(-h, --help)                            Show this help message");
-      console.log("  init <target_path> [options]                Initialize a new ScaffScript project");
-      console.log("    options:");
-      console.log("      -t, --template=<template>               Specify the template to use (bun, pnpm, npm). Default: npm");
-      console.log("      --git                                   Initialize a new Git repository");
-      console.log("      --new                                   Create a new GameMaker project");
+      console.log("  generate <source_path> <project_path>      Generate source code from the given path to the given project");
+      console.log("    aliases: gen");
+      console.log("    example: generate ./src ./my-game.yyp");
+      console.log("  help                                       Show this help message");
+      console.log("    aliases: -h, --help");
       console.log("");
       return {
         cmd: "help"
       };
-    case "init":
-      const targetPath = args[1];
-      const options = [...args];
-      options.shift();
-      const template = options.find((opt) => opt.startsWith("--template") || opt.startsWith("-t"))?.split("=")[1] ?? "npm";
-      const initGit = options.includes("--git");
-      const isNew = options.includes("--new");
-      if (!targetPath) {
-        log.error("No path specified. Please specify a valid path. Aborting...");
-        return null;
-      }
-      if (!["bun", "pnpm", "npm"].includes(template)) {
-        log.error(`Invalid template: \x1B[33m${template}\x1B[0m. Please specify a valid template (\x1B[32mbun\x1B[0m or \x1B[32mnode\x1B[0m). Aborting...`);
-        return null;
-      }
-      return {
-        cmd: "init",
-        targetPath,
-        template,
-        initGit,
-        isNew
-      };
     default:
       log.error(`Invalid command: \x1B[33m${cmd}\x1B[0m. Aborting...`);
       return null;
@@ -363,30 +334,44 @@ function getTabLevels(str, tabType) {
 }
 // package.json
 var package_default = {
-  name: "scaffscript",
-  version: "0.1.2",
-  description: "A superset language of GML with TypeScript-like module system",
+  name: "@scaffscript/core",
+  version: "0.1.5",
+  repository: {
+    type: "git",
+    url: "https://github.com/undervolta/scaffscript"
+  },
   main: "dist/index.cjs",
+  devDependencies: {
+    "@types/bun": "latest"
+  },
+  peerDependencies: {
+    typescript: "^5"
+  },
   bin: {
     scaff: "./dist/index.cjs"
   },
-  type: "module",
-  files: ["dist"],
+  description: "A minimal superset language of GML with TypeScript-like module system",
+  files: [
+    "dist"
+  ],
+  keywords: [
+    "gamemaker",
+    "gml",
+    "scaff",
+    "script",
+    "superset",
+    "module",
+    "cli"
+  ],
+  license: "MIT",
   scripts: {
-    build: "bun run build:node",
+    build: "bun run build:all",
     "build:node": "bun build src/index-node.ts --outfile dist/index.cjs --target node --format cjs",
-    "build:bun": "bun build src/index-bun.ts --outfile dist/index.mjs --target bun --format esm",
+    "build:bun": "bun build src/index-bun.ts --outfile build/index.mjs --target bun --format esm",
     "build:all": "bun run build:node && bun run build:bun",
     dev: "bun run src/index-node.ts"
   },
-  keywords: ["gamemaker", "gml", "scaff", "script", "superset", "module", "cli"],
-  license: "MIT",
-  devDependencies: {
-    "@types/bun": "latest"
-  },
-  peerDependencies: {
-    typescript: "^5"
-  }
+  type: "module"
 };
 
 // src/parser/special-value.ts
@@ -2210,7 +2195,7 @@ async function integrateSourceCodes(genFile, config, projectPath) {
     await modifyYyProject("add", projectPath, newResources, newFolders);
   if (!config.acceptAllIntegrations) {
     console.log("---");
-    log.info(`\x1B[34macceptAllIntegrations\x1B[0m flag is set to \x1B[33mfalse\x1B[0m in the \x1B[32mscaff.config.ts\x1B[0m. Please review the generated source codes before integrating.`);
+    log.info(`\x1B[34macceptAllIntegrations\x1B[0m flag is set to \x1B[33mfalse\x1B[0m in the \x1B[32mscaff.config\x1B[0m. Please review the generated source codes before integrating.`);
     const deleteResources = [];
     for (const [path3, data] of integrations) {
       const pathSlice = path3.split("/");
@@ -2310,14 +2295,10 @@ async function main() {
           log.info("Program executed successfully. Thanks for using ScaffScript!");
       } else {
         console.log("---");
-        log.info("\x1B[34mnoIntegration\x1B[0m flag is set to \x1B[33mtrue\x1B[0m in the \x1B[32mscaff.config.ts\x1B[0m. No source code will be integrated. Thanks for using ScaffScript!");
+        log.info("\x1B[34mnoIntegration\x1B[0m flag is set to \x1B[33mtrue\x1B[0m in the \x1B[32mscaff.config\x1B[0m. No source code will be integrated. Thanks for using ScaffScript!");
       }
       console.log("");
       break;
-    case "init":
-      log.info("ScaffScript project initializer hasn't been implemented yet. Please use the installation guide in the documentation.");
-      return;
-      break;
   }
   console.log("");
 }

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+export type ScaffConfig = {
+	/**
+     * accept all generated files to be integrated without manual confirmation (default = false)
+     */
+    acceptAllIntegrations: boolean;		
+    
+    /**
+     * clear the output directory before generating source code (default = false)
+     */
+	clearOutputDir: boolean;						
+	
+	/**
+     * starting value for the counter special value (default = 1)
+     */
+	counterStart: number;							
+	
+	/**
+     * debug level (default = 0, 0 = no debug, 1 = basic debug, 2 = verbose debug)
+     */
+	debugLevel: 0 | 1 | 2;							
+	
+	/**
+     * integration options
+     */
+	integrationOption: ScaffIntegrationOptions;
+	
+	/**
+     * don't backup the original files before integration (default = false)
+     */
+	noBackup: boolean;								
+	
+	/**
+     * don't integrate the files to GM project (default = false)
+     */
+	noIntegration: boolean;							
+	
+	/**
+     * what to do when something is not found (default = "error")
+     */
+	onNotFound: "error" | "ignore";					
+	
+	/**
+     * path aliases (default = {})
+     */
+	path: Record<string, string>;					
+	
+	/**
+     * whether the script is running in production mode (default = false)
+     */
+	production: boolean;							
+	
+	/**
+     * tab type to use when generating source code (default = "1t")
+     */
+	tabType: "1t" | "2s" | "4s";					
+	
+	/**
+     * target platform for the generated code (default = "all"). only used for tree-shaking purpose
+     */
+	targetPlatform: ScaffIntegrationTargetPlatform;	
+	
+	/**
+     * whether to use GM asset path when integrating files (default = false). asset path: `scripts` and `objects`
+     */
+	useGmAssetPath: boolean;						
+};
+
+type ScaffIntegrationOptions = Partial<{
+	isDnd: boolean;
+}>;
+
+type ScaffIntegrationTargetPlatform =
+	| "all" 
+	| "android"
+	| "gxgames"
+	| "html5"
+	| "ios"
+	| "linux"
+	| "mac"
+	| "ps4"
+	| "ps5"
+	| "reddit"
+	| "switch"
+	| "switch2"
+	| "tvos"
+	| "ubuntu"
+	| "windows"
+	| "xboxone"
+	| "xboxseries"
+;