Merge branch 'main' into development

.github/workflows/cl.yml

@@ -24,10 +24,12 @@ jobs:
           find ./docs/* -maxdepth 5 -name package.json -execdir sh -c 'pwd && npm install' \;
 
       - name: Type Check
-        run: tsc --build --verbose
+        run: | 
+          tsc --build --verbose
+          cp -r dist/* .
 
       - name: Format Check
-        run: node ./tools/index.js
+        run: node ./dist/tools/index.js
         env:
           event_name: ${{ github.event_name }}
 

.github/workflows/dependency-update.yml

@@ -24,7 +24,7 @@ jobs:
 
       - name: Update dependency
         id: update
-        run: node ./tools/dependency.js
+        run: node ./dist/tools/dependency.js
 
       - name: Create Pull Request
         id: cpr

.gitignore

@@ -1,11 +1,3 @@
-# Dependency directories
-node_modules/
-
-# Tools build files
-tools/**/*.js
-tools/**/*.js.map
-tools/**/*.d.ts
-
 # Logs
 logs
 *.log
@@ -15,5 +7,127 @@ yarn-error.log*
 lerna-debug.log*
 .pnpm-debug.log*
 
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
 # TypeScript cache
 *.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# scriptapi
+tools/*.js

CONTRIBUTING.md

@@ -2,56 +2,47 @@
 
 Contributing infomation. This info changes because Script API is currently in active development, and breaking changes are frequent.
 
-## Scripts
-
-When submitting a new package. The scripts are assumed that they can be used with the latest beta module of script modules in latest version of Minecraft Preview, the following is a reference of a manifest dependencies and NPM packages for meeting the criteria of submitting or updating a script sample.
-
-**manifest.json**
-
-This repository may have scripts that requires the following dependencies with their latest module version:
-
-```json
-"dependencies": [
-    {
-        "module_name": "@minecraft/server",
-        "version": "1.2.0-beta"
-    },
-    {
-        "module_name": "@minecraft/server-editor",
-        "version": "0.1.0-beta"
-    }
-    {
-        "module_name": "@minecraft/server-ui",
-        "version": "1.0.0-beta"
-    },
-    {
-        "module_name": "@minecraft/server-gametest",
-        "version": "1.0.0-beta"
-    },
-    {
-        "module_name": "@minecraft/server-admin",
-        "version": "1.0.0-beta"
-    },
-    {
-        "module_name": "@minecraft/server-net",
-        "version": "1.0.0-beta"
-    }
-]
-```
+## Creating a new script sample
+
+- Create a new directory for your script sample in the [**scripts**](./scripts/) directory. The directory name is your sample name and should be is unique and infomative.
+
+- Create a folder structure based on the following:
+
+| File                     | Purpose                            |
+| ------------------------ | ---------------------------------- |
+| `index.js` or `index.ts` | This is main file for the package. |
+| `README.md`              | Infomation for the package.        |
 
-This repository may have scripts that requires the following capabilities:
+In the main file, you must input basic credentials for the scripts with the right format. For example, here are the first few lines of script example:
 
-```json
-"capabilities": [
-    "editorExtension",
-    "script_eval"
-]
+```js
+// Script example for ScriptAPI
+// Author: Alice <https://github.com/alice>
+//         Bob <https://github.com/bob>
+//         Steve <https://steve.com/>
+// Project: https://github.com/JaylyDev/ScriptAPI
 ```
 
-**NPM packages:**
+In order for the pull request to be merged, the scripts must pass TypeScript Compiling process for all JavaScript/TypeScript files.
+
+![image](https://github.com/JaylyDev/ScriptAPI/assets/121162959/a0db5db6-864a-4f56-a8f5-01fc5c12167e)
+
+> Above image shows all checks have passed and the pull request should be able to be merged.
+
+If the check did not pass, go to the 'details' section and see what section of the check went wrong, and attempt to fix the issue by pushing another commit to your branch.
+
+## Create an editor extension sample
+
+An editor extension sample should only be used in Minecraft Editor, otherwise the sample should be hosted in 'scripts' folder.
+
+- Create an editor extension sample in [editorExtensions](./editorExtensions/) directory.
+
+- Create the same folder structure as used in scripts folder and a header in main file like creating a new script sample.
+
+- We recommend using TypeScript for editor extension samples.
+
+## Don't edit docs folder
+
+Documentation are no longer being updated as mentioned in README.
 
-- [`@minecraft/server@beta`](https://www.npmjs.com/package/@minecraft/server/v/beta)
-- [`@minecraft/server-ui@beta`](https://www.npmjs.com/package/@minecraft/server-ui/v/beta)
-- [`@minecraft/server-net@beta`](https://www.npmjs.com/package/@minecraft/server-net/v/beta)
-- [`@minecraft/server-gametest@beta`](https://www.npmjs.com/package/@minecraft/server-gametest/v/beta)
-- [`@minecraft/server-admin@beta`](https://www.npmjs.com/package/@minecraft/server-admin/v/beta)
+Please do not submit any pull requests that changes any content to the docs directory. Instead, please visit [Bedrock Wiki](https://wiki.bedrock.dev/scripting/starting-scripts) and perhaps contribute scripting documentation in Bedrock Wiki GitHub repository: https://github.com/Bedrock-OSS/bedrock-wiki/tree/wiki/docs/scripting

README.md

@@ -2,73 +2,39 @@
 
 This repository is filled with community driven script samples for Minecraft Bedrock Script API.
 
-## Script Samples
+<hr/>
 
-- ### [scripts](./scripts/)
+### 🔴 USE `stable` not `main` 🔴
 
-  Community driven scripts that use Script API to do all kinds of crazy stuff in Minecraft.
-
-  > ⚠️ Some scripts might use API modules that are only enabled in specific environments, including:
-  > - `@minecraft/server-net` and `@minecraft/server-admin`: Modules that can only be used in [Bedrock Dedicated Servers](https://www.minecraft.net/en-us/download/server/bedrock).
-  > - `@minecraft/server-editor` and `@minecraft/server-editor-bindings`: Modules that can only be used on Editor projects in [Minecraft Editor](https://github.com/mojang/minecraft-editor).
-
-- ### [docs](./docs/)
-  Contains technical documentation of Script API features.
-  > 🚫 Documentation are no longer being updated. Check out [Bedrock Wiki](https://wiki.bedrock.dev/scripting/starting-scripts) and [Microsoft Learn](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/) for up-to-date infomation.
-
-## Contributing
-
-Please contribute to this repository if you can.
-
-The repository features a Pull Request system that inspires heavily from [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped). This implementation serves to ensure the attribution of code ownership to the script authors who manages of their scripts.
+**Check out the `stable` branch from here: https://github.com/JaylyDev/ScriptAPI/tree/stable**.
+The `main` branch is used for script development for Minecraft Preview and may often be in a **broken** state.
 
-To create a new script package, create a folder structure based on the following:
+<hr/>
 
-| File                     | Purpose                                                                                              |
-| ------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `index.js` or `index.ts` | This is main file for the package.                                                                   |
-| `tests.js` or `tests.ts` | This contains sample code which tests the typings. This code does _not_ run, but it is type-checked. |
-| `tsconfig.json`          | This allows you to run `tsc` within the package.                                                     |
-| `README.md`              | Infomation for the package.                                                                          |
+- ### [Scripts](./scripts/)
 
-To add yourself as a script author:
-
-Adding your name to the end of the line, as in `// Author: Alice <url>, Bob <url>`.
-Or if there are more people, it can be multiline
-
-```js
-// Author: Alice <url>
-//         Bob <url>
-//         Steve <url>
-//         John <url>
-```
-
-Each package is versioned via GitHub repository tags. In order to secure credentials for scripts, each main file requires basic credentials with the right format. For example, here are the first few lines of script example:
-
-```js
-// Script example for ScriptAPI
-// Author: Alice <https://github.com/alice>
-//         Bob <https://github.com/bob>
-//         Steve <https://steve.com/>
-// Project: https://github.com/JaylyDev/ScriptAPI
-```
+  Community driven scripts that use Script API to do all kinds of crazy stuff in Minecraft.
 
-### Script Versioning
+  > ⚠️ Some scripts might use API modules that are only enabled in specific runtime environments, including:
+  >
+  > - `@minecraft/server-net` and `@minecraft/server-admin`: Modules that can only be used in [Bedrock Dedicated Servers](https://www.minecraft.net/en-us/download/server/bedrock).
 
-The script samples are intended to be used within the latest version of Minecraft or Minecraft Preview, using latest development version of Script API modules.
+- ### [Editor Extensions](./editorExtensions/)
 
-For submitting or updating script samples, you must upload scripts that works in the latest version of Script API modules in latest Minecraft Preview. For more infomation please visit [here](./CONTRIBUTING.md).
+  Community driven editor extensions samples for editing Minecraft worlds. Only available on Editor projects in [Minecraft Editor](https://github.com/mojang/minecraft-editor).
 
-To access older versions of scripts, this repository uses [GitHub's tags feature](https://github.com/JaylyDev/ScriptAPI/tags) to allow users to access previous versions of repository for scripts that uses a specific Minecraft version.
+  Highly recommend checking out Mojang's [editor extension starter kit](https://github.com/Mojang/minecraft-editor-extension-starter-kit) if you're experimenting with editor API for the first time!
 
-![github_tags](https://user-images.githubusercontent.com/65847850/222926832-8c8db1d5-f6d6-41be-bfeb-f4efdd5d46b5.png)
+- ### [docs](./docs/)
+  Contains technical documentation of Script API features.
+  > **🚫 Documentation are no longer being updated**. Check out [Microsoft Learn](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/) and [Bedrock Wiki](https://wiki.bedrock.dev/scripting/starting-scripts) for up-to-date infomation.
 
-## Script status
+## Contributing
 
-This repository uses TypeScript compiler to test script files by validing with declaration files of Script API modules, making sure they are up-to-date when using in the latest Minecraft versions.
+Please contribute to this repository if you can. Check out [**Contributing Guidelines**](./CONTRIBUTING.md) for more infomation.
 
-![success_checks](https://user-images.githubusercontent.com/65847850/222813970-7f24a869-37a5-4e73-b2fd-03f321fdb4d1.png)
+## License
+This project is licensed under the MIT license.
 
-Most of the time the checks succeed, which means scripts inside should not have any syntax errors when using in stable version of Minecraft.
+Copyrights on the script files are each contributor listed at the beginning of each script file.
 
-If the check failed, it's worth creating a bug report if a fix is not implemented, or a pull request if you may find a solution to a fix to the problem.

docs/JavaScript/JSON/stringify.md

@@ -16,9 +16,11 @@ A JSON string representing the given value, or undefined.
 
 #### Stringify native objects
 
-Minecraft has modified `JSON.stringify` function so that when stringify a native object, it always return `{}`.
+As you may have already noticed, when you `JSON.stringify()` native objects, the properties that this native object has are not displayed, this has the consequence that the `JSON.stringify()` function only returns an empty object `{}`.
+Why is it like this?
+The answer is quite obvious, native class instances have no properties, therefore they cannot be displayed, native classes have getters that are always called from the prototype of that instance, and J`JSON.stringify()` does not include prototypes, that's all, but this does not apply to interfaces, they do not have native prototypes therefore it is possible to display them as, for example, a `Vector3` interface.
 
-A workaround is to deep copy the JSON object. Highly recommend using this package to display native objects in string.
+A workaround is to deep copy the JSON object. Highly recommend using this package to display class insatnce properties.
 - https://github.com/zxdong262/deep-copy
 
 ## Learn more

docs/JavaScript/README.md

@@ -36,7 +36,7 @@ These features exist in vanilla (most engine / frameworks) JavaScript global sco
 - [Infinity](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
 - [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
   - [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
-  - [JSON.stringify](./JSON/stringify.md) (Modified in Minecraft, click for more infomation.)
+  - [JSON.stringify](./JSON/stringify.md) (Why can't stringify native objects? `{}`, click for more infomation.)
 - [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)
 - [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
 - [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)

docs/MinecraftApi/@minecraft/server/DynamicProperty/registerWorldDynamicProperties.js

@@ -1,6 +1,6 @@
 import { DynamicPropertiesDefinition, world } from "@minecraft/server";
 
-world.events.worldInitialize.subscribe(({propertyRegistry}) => {
+world.afterEvents.worldInitialize.subscribe(({propertyRegistry}) => {
   // add boolean dynamic property
   const dynamicProperty = new DynamicPropertiesDefinition();
   dynamicProperty.defineBoolean("my_boolean");
@@ -22,4 +22,4 @@ world.setDynamicProperty("my_string", 'Hi mom');
 
 world.getDynamicProperty("my_boolean"); // true
 world.getDynamicProperty("my_number"); // 100
-world.getDynamicProperty("my_string"); // 'Hi mom'
+world.getDynamicProperty("my_string"); // 'Hi mom'