Merge branch 'master' into colorbycssnames

.github/workflows/test.yml

@@ -26,4 +26,5 @@ jobs:
       - name: Run vitests
         run: pnpm run test:vite
       - name: Upload Package
+        if: ${{ github.event_name == 'pull_request' }}
         run: pnpx pkg-pr-new publish

CHANGELOG.md

@@ -1,4 +1,4 @@
-# v4000.0.0
+# v4000.0.0 (unreleased)
 
 - Added clipLineToRect
 - Replaced the Separating Axis Theorem (SAT) with the Gilbert–Johnson–Keerthi
@@ -20,7 +20,19 @@
   myCursor.move(vec2(100, 200)); // move as your wish
   ```
 
-# v4000.0.0 and v3001.0.0
+# v3001.1.0: A perfectionist skull (unreleased)
+
+- Added many JSDoc specifiers on many functions (@require, @deprecated, @since,
+  @group, etc)
+- Added `getLayers()` to get the layers list
+- Added `getDefaulLayer()` to get the default layer
+- Deprecated camera methods `camScale()`, `camPos()` and `camRot()` in favor of
+  `setCamScale()`, `getCamScale()`, `setCamPos()`, `getCamPos()`, `setCamRot()`
+  and `getCamRot`.
+- Deprecated `camFlash()` in favor of `flash()`, for a `shake()`-like name.
+- Deprecated `camTransform()` in favor of `getCamTransform()`.
+
+# v3001.0.0: Spooky Beans!
 
 ## Input
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+![KAPLAY](/kaplay.webp)
+# KAPLAY Code of Conduct
+
+Based on the [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html) 
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone.
+
+We pledge to act and interact in ways that contribute to an open, 
+welcoming, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission, accidents such as
+  using personal email in a co-author is allowed, but try to avoid
+  that from happening
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address that ends with @kaplayjs.com,
+posting via an official social media account, talking in discord, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+support@kaplayjs.com, or #support in the Discord, 
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary suspension or
+permanent ban.
+
+### 3. Temporary Suspension
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, spamming messages on any of our platforms, or scamming other users.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+**Important**: We dont give this punishment regularly, 
+this is only used in extreme circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -51,6 +51,55 @@ definition, the JSDoc comments are on `types.ts`.
 
 **Help on improving the documentation is appreciated!**
 
+## JSDoc comments
+
+There is the structure of a JSDoc comment:
+
+- The Description of the member.
+- `@deprecated` when the member is deprecated.
+- `@requires` when the member requires something to work. Usually a component.
+- `@param` for each parameter. Each parameter should have - at start.
+- `@example` for 1 (and only one) example.
+- `@returns` for the return value description.
+- `@since` for the version when the member was added.
+- `@group` for the group of the member.
+
+Example:
+
+````ts
+/**
+   * Attach and render a circle to a Game Object.
+   *
+   * @param radius - The radius of the circle.
+   * @param opt - Options for the circle component. See {@link CircleCompOpt `CircleCompOpt`}.
+   *
+   * @example
+   * ```js
+   * add([
+   *     pos(80, 120),
+   *     circle(16),
+   * ])
+   * ```
+   *
+   * @returns The circle comp.
+   * @since v2000.0
+   * @group Components
+   */
+  circle(radius: number, opt?: CircleCompOpt): CircleComp;
+````
+
+## Abbreviations
+
+- `opt` for an options object.
+- `pos` for a position vector.
+- `dir` for a direction vector.
+- `comp` for a component.
+- `game obj` word for a game object.
+- `lst` for a list of something.
+- `action` the callback that is executed when smt happens.
+- `btn` button
+- `k` in some contexts, key, in others, KAPLAY interface
+
 # Before commit
 
 1. Follow our [conventional commits](#conventional-commits-guide) format. You

examples/button.js

@@ -23,7 +23,7 @@ function addButton(
         scale(1),
         anchor("center"),
         outline(4),
-        color(0, 0, 0),
+        color(255, 255, 255),
     ]);
 
     // add a child object that displays the text

examples/camera.js

@@ -54,12 +54,12 @@ const player = level.get("player")[0];
 // Will run every frame
 player.onUpdate(() => {
     // Set the viewport center to player.pos
-    camPos(player.worldPos());
+    setCamPos(player.worldPos());
 });
 
 // Set the viewport center to player.pos whenever their physics are resolved
 player.onPhysicsResolve(() => {
-    camPos(player.worldPos());
+    setCamPos(player.worldPos());
 });
 
 // When the player collides with a coin object
@@ -69,7 +69,7 @@ player.onCollide("coin", (coin) => {
     play("score");
     score++;
     // Zoooom in!
-    camScale(2);
+    setCamScale(2);
 });
 
 // Movements

examples/concert.js

@@ -158,8 +158,8 @@ player.onHeadbutt((block) => {
 
 onUpdate(() => {
     if (!burping) return;
-    camPos(camPos().lerp(player.pos, dt() * 3));
-    camScale(camScale().lerp(vec2(5), dt() * 3));
+    setCamPos(getCamPos().lerp(player.pos, dt() * 3));
+    setCamScale(getCamScale().lerp(vec2(5), dt() * 3));
 });
 
 const lyrics =

examples/platformBox.js

@@ -71,5 +71,5 @@ onKeyDown("right", () => {
 });
 
 onUpdate(() => {
-    camPos(player.worldPos());
+    setCamPos(player.worldPos());
 });

examples/platformEffector.js

@@ -57,7 +57,7 @@ const player = level.get("player")[0];
 
 // Always look at player
 onUpdate(() => {
-    camPos(player.worldPos());
+    setCamPos(player.worldPos());
 });
 
 // Movements

examples/platformer.js

@@ -219,7 +219,7 @@ scene("game", ({ levelId, coins } = { levelId: 0, coins: 0 }) => {
     // action() runs every frame
     player.onUpdate(() => {
         // center camera to player
-        camPos(player.pos);
+        setCamPos(player.pos);
         // check fall death
         if (player.pos.y >= FALL_DEATH) {
             go("lose");
@@ -234,7 +234,7 @@ scene("game", ({ levelId, coins } = { levelId: 0, coins: 0 }) => {
 
     player.onPhysicsResolve(() => {
         // Set the viewport center to player.pos
-        camPos(player.pos);
+        setCamPos(player.pos);
     });
 
     // if player onCollide with any obj with "danger" tag, lose

examples/spriteatlas.js

@@ -320,12 +320,12 @@ const dirs = {
 };
 
 player.onUpdate(() => {
-    camPos(player.pos);
+    setCamPos(player.pos);
 });
 
 player.onPhysicsResolve(() => {
     // Set the viewport center to player.pos
-    camPos(player.pos);
+    setCamPos(player.pos);
 });
 
 onKeyDown("right", () => {

package.json

@@ -46,21 +46,21 @@
   "scripts": {
     "dev": "NODE_ENV=development node scripts/dev.js",
     "win:dev": "set NODE_ENV=development && node scripts/dev.js",
-    "build": "npm run dts && node scripts/build.js && npm run merge-dts",
+    "build": "tsc --p tsconfig.dts.json && node scripts/build.js && npm run doc-dts",
     "check": "tsc",
     "fmt": "dprint fmt",
     "test": "node scripts/test.js",
-    "merge-dts": "dts-bundle-generator -o dist/doc.d.ts dist/declaration/index.d.ts",
+    "doc-dts": "dts-bundle-generator -o dist/doc.d.ts dist/declaration/index.d.ts",
     "test:vite": "vitest",
     "desktop": "tauri dev",
     "prepare": "npm run build",
-    "publish:next": "npm publish --tag next",
-    "dts": "tsc --p tsconfig.dts.json"
+    "publish:next": "npm publish --tag next"
   },
   "devDependencies": {
     "@kaplayjs/dprint-config": "^1.1.0",
     "dprint": "^0.45.1",
     "dts-bundle-generator": "^9.5.1",
+    "ejs": "^3.1.10",
     "esbuild": "^0.21.5",
     "express": "^4.21.1",
     "puppeteer": "^22.15.0",