diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000000..3920bcd3127 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,41 @@ +# This file normalizes line endings stored in the repo to LF (Unix/Git). +# Contributors are still able to use their native line endings locally. +# More info here: https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings + +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files to be normalized on checkin +# and converted back to native line endings on checkout. +*.js text +*.json text +*.mjs text +*.cjs text +*.jsx text +*.ts text +*.txt text +*.tsx text +*.md text +*.html text +*.gltf text +*.glsl text +*.css text +*.mustache text +*.obj text +*.atlas text +*.yaml text +*.babelrc text + +# Denote all files that are truly binary and should therefore not be modified. +*.png binary +*.jpg binary +*.glb binary +*.fbx binary +*.wasm binary +*.basis binary +*.bin binary +*.dds binary +*.drc binary +*.mp3 binary +*.mp4 binary +*.gz binary diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 55129c0e681..984278aedc9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -46,6 +46,8 @@ You may use the following JavaScript language features in the engine codebase: * [Optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) * [Static keyword](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) * [Template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) +* [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) - only functionality supported by all browsers, including Safari 8 - see the table at the end of the page. `for..of` type of loop should not be used to iterate a set as it is not supported on Safari 8. +* [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) - only functionality supported by all browsers, including Safari 8 - see the table at the end of the page. `for..of` type of loop should not be used to iterate a map as it is not supported on Safari 8. ### Opening braces should be on the same line as the statement @@ -173,12 +175,30 @@ let mixedCase = 1; // Function are usually variables so should be mixedCase // (unless they are class constructors) let myFunction = function () { }; +let myFunction = () => { }; // Constants should be ALL_CAPITALS separated by underscores. // Note, ES5 doesn't support constants, // so this is just convention. const THIS_IS_CONSTANT = "well, kind of"; +// Enum constants follow similar rules as normal constants. In general, +// the enum consists of the type, and its values. +// In other languages, this is implemented as +// enum CubeFace { +// PosX: 0, +// PosY: 1 +// } +// Due to the lack of native enum support by JavaScript, the enums are +// represented by constants. The constant name contains the enum name without +// the underscores, followed by the values with optional underscores as +// needed to improve the readibility. This is one possible implementation: +const CUBEFACE_POSX = 0; +const CUBEFACE_POSY = 1; +// and this is also acceptable +const CUBEFACE_POS_X = 0; +const CUBEFACE_POS_Y = 1; + // Private variables should start with a leading underscore. // Note, you should attempt to make private variables actually private using // a closure. diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 386ca986bc1..00000000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,14 +0,0 @@ -version: 2 -updates: - - package-ecosystem: "npm" - # Look for `package.json` and `lock` files in the `root` directory - directory: "/" - # Check the npm registry for updates every day (weekdays) - schedule: - interval: "monthly" - - - package-ecosystem: "github-actions" - directory: "/" - # Look for `package.json` and `lock` files in the `root` directory - schedule: - interval: "monthly" diff --git a/.github/renovate.json b/.github/renovate.json new file mode 100644 index 00000000000..aaf421f5f54 --- /dev/null +++ b/.github/renovate.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "extends": [ + "config:recommended" + ], + "packageRules": [ + { + "matchManagers": [ + "npm" + ], + "groupName": "all npm dependencies", + "schedule": [ + "on monday at 10:00am" + ] + }, + { + "matchDepTypes": ["devDependencies"], + "rangeStrategy": "pin" + }, + { + "matchDepTypes": ["dependencies"], + "rangeStrategy": "widen" + } + ], + "ignorePaths": [".nvmrc"] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aef965d7ec0..12da1f5a1bd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,72 +1,151 @@ name: CI on: + workflow_dispatch: push: - branches: [ master ] + branches: [ main ] pull_request: - branches: [ master ] + branches: [ main ] + +concurrency: + group: ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +permissions: + contents: read jobs: build: name: Build runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout code - uses: actions/checkout@v2 - - name: Setup Node.js 12.x - uses: actions/setup-node@v2.4.0 + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 with: - node-version: 12.x + node-version: 22.x + cache: 'npm' + - name: Install dependencies - run: npm ci + run: npm clean-install --progress=false --no-fund + - name: Build PlayCanvas run: npm run build + - name: Run Publint + run: npm run publint + + docs: + name: Docs + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: 'npm' + + - name: Install dependencies + run: npm clean-install --progress=false --no-fund + + - name: Build API reference manual + run: npm run docs + lint: name: Lint runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout code - uses: actions/checkout@v2 - - name: Setup Node.js 12.x - uses: actions/setup-node@v2.4.0 + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 with: - node-version: 12.x + node-version: 22.x + cache: 'npm' + - name: Install dependencies - run: npm ci + run: npm clean-install --progress=false --no-fund + - name: Run ESLint run: npm run lint - typescript-definitions: - name: Typescript Definitions + - name: Run ESLint on examples + working-directory: ./examples + run: | + npm clean-install --progress=false --no-fund + npm run lint + + typescript-declarations: + name: TypeScript Declarations runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout code - uses: actions/checkout@v2 - - name: Setup Node.js 12.x - uses: actions/setup-node@v2.4.0 + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 with: - node-version: 12.x + node-version: 22.x + cache: 'npm' + - name: Install dependencies - run: npm ci - - name: Build Typescript definitions - run: npm run test:tsd + run: npm clean-install --progress=false --no-fund + + - name: Build TypeScript declarations + run: npm run build:types + + - name: Compile TypeScript declarations + run: npm run test:types unit-test: name: Unit Test runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout code - uses: actions/checkout@v2 - - name: Setup Node.js 12.x - uses: actions/setup-node@v2.4.0 + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 with: - node-version: 12.x + node-version: 22.x + cache: 'npm' + - name: Install dependencies - run: npm ci - - name: Build PlayCanvas (ES5-only) - run: npm run build:es5 - - name: Install X virtual framebuffer - run: sudo apt-get install xvfb + run: npm clean-install --progress=false --no-fund + - name: Run unit tests - run: xvfb-run --auto-servernum npm run test + run: npm test + + build-examples: + name: Build Examples Browser + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js 18.x + uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: 'npm' + + - name: Install dependencies + run: npm clean-install --progress=false --no-fund + + - name: Build Examples Browser + working-directory: ./examples + run: | + npm clean-install --progress=false --no-fund + npm run build diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml deleted file mode 100644 index 666132e9a32..00000000000 --- a/.github/workflows/codeql-analysis.yml +++ /dev/null @@ -1,71 +0,0 @@ -# For most projects, this workflow file will not need changing; you simply need -# to commit it to your repository. -# -# You may wish to alter this file to override the set of languages analyzed, -# or to provide custom queries or build logic. -# -# ******** NOTE ******** -# We have attempted to detect the languages in your repository. Please check -# the `language` matrix defined below to confirm you have the correct set of -# supported CodeQL languages. -# -name: "CodeQL" - -on: - push: - branches: [ master ] - pull_request: - # The branches below must be a subset of the branches above - branches: [ master ] - schedule: - - cron: '28 18 * * 3' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-latest - permissions: - actions: read - contents: read - security-events: write - - strategy: - fail-fast: false - matrix: - language: [ 'javascript' ] - # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ] - # Learn more: - # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed - - steps: - - name: Checkout repository - uses: actions/checkout@v2 - - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v1 - with: - languages: ${{ matrix.language }} - # If you wish to specify custom queries, you can do so here or in a config file. - # By default, queries listed here will override any specified in a config file. - # Prefix the list here with "+" to use these queries and those in the config file. - # queries: ./path/to/local/query, your-org/your-repo/queries@main - - # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). - # If this step fails, then you should remove it and run the build manually (see below) - - name: Autobuild - uses: github/codeql-action/autobuild@v1 - - # ℹ️ Command-line programs to run using the OS shell. - # 📚 https://git.io/JvXDl - - # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines - # and modify them (or add more) to build your code if your project - # uses a compiled language - - #- run: | - # make bootstrap - # make release - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v1 diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 00000000000..36e28451ae3 --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,56 @@ +name: Publish to npm + +on: + push: + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' + - 'v[0-9]+.[0-9]+.[0-9]+-preview.[0-9]+' + +jobs: + publish-npm: + runs-on: ubuntu-latest + if: github.repository == 'playcanvas/engine' + steps: + - name: Check out code + uses: actions/checkout@v4 + + - name: Set up Node.js 18.x + uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: 'npm' + registry-url: 'https://registry.npmjs.org/' + + - name: Parse tag name + run: | + TAG_NAME=${GITHUB_REF#refs/tags/} + echo "TAG=${TAG_NAME}" >> $GITHUB_ENV + echo "VERSION=${TAG_NAME/v/}" >> $GITHUB_ENV + + - name: Install Dependencies + run: npm install + + - name: Build PlayCanvas + run: npm run build + + - name: Run Publint + run: npm run publint + + - name: Publish to npm + run: | + if [[ "${{ env.TAG }}" =~ "preview" ]]; then + tag=preview + else + tag=latest + fi + npm publish --tag $tag + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Publish to code.playcanvas.com + run: | + if ! curl -sS -X POST -H "Content-Type: application/json" \ + -d '{ "engineVersion": "${{ env.VERSION }}" }' ${{ secrets.PUBLISH_ENDPOINT }}; then + echo "Failed to publish to code.playcanvas.com" + exit 1 + fi \ No newline at end of file diff --git a/.gitignore b/.gitignore index ebc034b381a..da5e5a75ce7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,16 @@ *.DS_Store -/build -/docs -node_modules/ .idea/ .vscode/ -npm-debug.log -.java-version -release.py -examples/node_modules +build +tree*.*.html +coverage +docs examples/dist +examples/node_modules +node_modules +npm-debug.log +types +stats.html +.npmrc +examples/.npmrc +.prettierrc diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 00000000000..3c032078a4a --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +18 diff --git a/LICENSE b/LICENSE index 41bbbfac990..72ef48075c0 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2011-2021 PlayCanvas Ltd. +Copyright (c) 2011-2024 PlayCanvas Ltd. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README-ja.md b/README-ja.md new file mode 100644 index 00000000000..5a517e5a0f1 --- /dev/null +++ b/README-ja.md @@ -0,0 +1,135 @@ +
+ + + +# PlayCanvas WebGL Game Engine + +[API Reference](https://api.playcanvas.com/modules/Engine.html) | [User Manual](https://developer.playcanvas.com) | [Examples](https://playcanvas.github.io) | [Forum](https://forum.playcanvas.com) | [Blog](https://blog.playcanvas.com) + +PlayCanvasは、オープンソースのゲームエンジンです。 + +HTML5とWebGLを使用してゲームやインタラクティブな3Dコンテンツをモバイルやデスクトップのブラウザで実行できます。 + +[![NPM version][npm-badge]][npm-url] +[![Minzipped size][minzip-badge]][minzip-url] +[![Average time to resolve an issue][resolution-badge]][isitmaintained-url] +[![Percentage of issues still open][open-issues-badge]][isitmaintained-url] +[![Twitter][twitter-badge]][twitter-url] + +[English](https://github.com/playcanvas/engine/blob/dev/README.md) +[中文](https://github.com/playcanvas/engine/blob/dev/README-zh.md) +[日本語](https://github.com/playcanvas/engine/blob/dev/README-ja.md) +[한글](https://github.com/playcanvas/engine/blob/dev/README-kr.md) + +## ショーケース + +PlayCanvasエンジンを使って[多くのゲームやアプリ](https://github.com/playcanvas/awesome-playcanvas) 公開されています。ここではその一部をご紹介します。 + +[![Seemore](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14705/319531/O4J4VU-image-25.jpg)](https://playcanv.as/p/MflWvdTW/) [![After The Flood](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/440410/98554E-image-25.jpg)](https://playcanv.as/p/44MRmJRU/) [![Casino](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/349824/U88HJQ-image-25.jpg)](https://playcanv.as/p/LpmXGUe6/) +[![Swooop](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/4763/TKYXB8-image-25.jpg)](https://playcanv.as/p/JtL2iqIH/) [![Master Archer](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/415995/10A5A9-image-25.jpg)](https://playcanv.as/p/JERg21J8/) [![Flappy Bird](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/8/375389/23PRTL-image-25.jpg)](https://playcanv.as/p/2OlkUaxF/) +[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/) + +他のゲームは[PlayCanvasのウェブサイト](https://playcanvas.com/explore)で見ることができます。 + +
+ +## 利用実績 + +PlayCanvasは、ビデオゲーム、広告、ビジュアライゼーションの分野で大手企業に採用されています。 +**Animech, Arm, BMW, Disney, Facebook, Famobi, Funday Factory, IGT, King, Miniclip, Leapfrog, Mojiworks, Mozilla, Nickelodeon, Nordeus, NOWWA, PikPok, PlaySide Studios, Polaris, Product Madness, Samsung, Snap, Spry Fox, Zeptolab, Zynga** + +## 機能 + +PlayCanvasはフル機能のゲームエンジンです。 + +* 🧊 **グラフィックス** - WebGL 1.0 & 2.0で構築された高度な2D + 3Dグラフィックスエンジン。 +* 🏃 **アニメーション** - キャラクターやシーンに対する強力なステートベースのアニメーション +* ⚛️ **物理** - 3Dリジッドボディ物理エンジン [ammo.js](https://github.com/kripken/ammo.js) +* 🎮 **インプット** - マウス、キーボード、タッチ、ゲームパッド、VRコントローラのAPI +* 🔊 **サウンド** - Web Audio APIを利用した3D位置情報サウンド +* 📦 **アセット** - [glTF 2.0](https://www.khronos.org/gltf/)、[Draco](https://google.github.io/draco/)、[Basis](https://github.com/BinomialLLC/basis_universal) の圧縮技術を利用した非同期型ストリーミングシステム +* 📜 **スクリプト** - TypeScriptとJavaScriptをサポート + +## 使用方法 + +シンプルなHello Worldの例です。 + +```js +import * as pc from 'playcanvas'; + +const canvas = document.createElement('canvas'); +document.body.appendChild(canvas); + +const app = new pc.Application(canvas); + +// fill the available space at full resolution +app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW); +app.setCanvasResolution(pc.RESOLUTION_AUTO); + +// ensure canvas is resized when window changes size +window.addEventListener('resize', () => app.resizeCanvas()); + +// create box entity +const box = new pc.Entity('cube'); +box.addComponent('model', { + type: 'box' +}); +app.root.addChild(box); + +// create camera entity +const camera = new pc.Entity('camera'); +camera.addComponent('camera', { + clearColor: new pc.Color(0.1, 0.2, 0.3) +}); +app.root.addChild(camera); +camera.setPosition(0, 0, 3); + +// create directional light entity +const light = new pc.Entity('light'); +light.addComponent('light'); +app.root.addChild(light); +light.setEulerAngles(45, 0, 0); + +// rotate the box according to the delta time since the last frame +app.on('update', dt => box.rotate(10 * dt, 20 * dt, 30 * dt)); + +app.start(); +``` + +このコードを自分で試すには[CodePen](https://codepen.io/playcanvas/pen/NPbxMj)をクリックします。 + +PlayCanvas Engine をベースにしたローカル開発環境の設定に関する完全ガイドは[こちら](https://developer.playcanvas.com/user-manual/engine/standalone/)で見つけることができます。 + +## ビルドの手順 + +[Node.js 18+](https://nodejs.org)がインストールされていることを確認します。次に、必要なNode.jsの依存関係をすべてインストールします。 + +```sh +npm install +``` + +これで、様々なオプションでビルドを実行できるようになりました。 + +| コマンド | 説明 | 出力先 | +| --------------- | ----------------------------------------------------- | ---------- | +| `npm run build` | すべてのエンジンビルドターゲットと型宣言をビルドする | `build` | +| `npm run docs` | エンジンの[APIリファレンスドキュメント][docs]をビルドする | `docs` | + +## PlayCanvasエディター + +PlayCanvas エンジンは、HTML5 アプリやゲームを作成するためのオープンソースのエンジンです。エンジンに加えて、[PlayCanvasエディター](https://playcanvas.com/)があります。 + +[![Editor](https://github.com/playcanvas/editor/blob/main/images/editor.png?raw=true)](https://github.com/playcanvas/editor) + +エディター関連のバグや問題については、[Editor's repo](https://github.com/playcanvas/editor)を参照してください。 + +[npm-badge]: https://img.shields.io/npm/v/playcanvas +[npm-url]: https://www.npmjs.com/package/playcanvas +[minzip-badge]: https://img.shields.io/bundlephobia/minzip/playcanvas +[minzip-url]: https://bundlephobia.com/result?p=playcanvas +[resolution-badge]: https://isitmaintained.com/badge/resolution/playcanvas/engine.svg +[open-issues-badge]: https://isitmaintained.com/badge/open/playcanvas/engine.svg +[isitmaintained-url]: https://isitmaintained.com/project/playcanvas/engine +[twitter-badge]: https://img.shields.io/twitter/follow/playcanvas.svg?style=social&label=Follow +[twitter-url]: https://twitter.com/intent/follow?screen_name=playcanvas +[docs]: https://api.playcanvas.com/modules/Engine.html diff --git a/README-kr.md b/README-kr.md new file mode 100644 index 00000000000..f5735de2697 --- /dev/null +++ b/README-kr.md @@ -0,0 +1,137 @@ +
+ + + +# PlayCanvas WebGL Game Engine + +[API Reference](https://api.playcanvas.com/modules/Engine.html) | [User Manual](https://developer.playcanvas.com) | [Examples](https://playcanvas.github.io) | [Forum](https://forum.playcanvas.com) | [Blog](https://blog.playcanvas.com) + +PlayCanvas는 오픈소스 게임 엔진입니다. + +HTML5와 WebGL을 사용하여 게임과 인터랙티브한 3D 콘텐츠를 모바일이나 데스크톱 브라우저에서 실행할 수 있습니다. + +[![NPM version][npm-badge]][npm-url] +[![Minzipped size][minzip-badge]][minzip-url] +[![Average time to resolve an issue][resolution-badge]][isitmaintained-url] +[![Percentage of issues still open][open-issues-badge]][isitmaintained-url] +[![Twitter][twitter-badge]][twitter-url] + +[English](https://github.com/playcanvas/engine/blob/master/README.md) +[中文](https://github.com/playcanvas/engine/blob/master/README-zh.md) +[日本語](https://github.com/playcanvas/engine/blob/master/README-ja.md) +[한글](https://github.com/playcanvas/engine/blob/master/README-kr.md) + +## Project Showcase + +PlayCanvas 엔진을 사용하여 [많은 게임과 앱](https://github.com/playcanvas/awesome-playcanvas#awesome-playcanvas- +)이 공개되어 있습니다. 다음은 그 일부를 소개하겠습니다. + +[![Seemore](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14705/319531/O4J4VU-image-25.jpg)](https://playcanv.as/p/MflWvdTW/) [![After The Flood](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/440410/98554E-image-25.jpg)](https://playcanv.as/p/44MRmJRU/) [![Casino](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/349824/U88HJQ-image-25.jpg)](https://playcanv.as/p/LpmXGUe6/) +[![Swooop](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/4763/TKYXB8-image-25.jpg)](https://playcanv.as/p/JtL2iqIH/) [![dev Archer](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/415995/10A5A9-image-25.jpg)](https://playcanv.as/p/JERg21J8/) [![Flappy Bird](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/8/375389/23PRTL-image-25.jpg)](https://playcanv.as/p/2OlkUaxF/) +[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/) + +다른 게임은 [Play Canvas 웹사이트](https://playcanvas.com/explore)에서 볼 수 있습니다. + +
+ +## Users + +PlayCanvas는 비디오 게임, 광고, 시각화 분야에서 대기업에 채용되고 있습니다. + +**Animech, Arm, BMW, Disney, Facebook, Famobi, Funday Factory, IGT, King, Miniclip, Leapfrog, Mojiworks, Mozilla, Nickelodeon, Nordeus, NOWWA, PikPok, PlaySide Studios, Polaris, Product Madness, Samsung, Snap, Spry Fox, Zeptolab, Zynga** + +## 특징 + +PlayCanvas는 완전한 기능의 게임 엔진입니다. + +* 🧊 **그래픽** - WebGL 1.0&2.0으로 구축된 고도의 2D+3D 그래픽 엔진. +* 🏃 **애니메이션** - 캐릭터나 장면에 대한 강력한 스테이트 기반 애니메이션 +* ⚛️ **물리** - 3D 리지드 바디 물리 엔진 [ammo.js](https://github.com/kripken/ammo.js) +* 🎮 **입력** - 마우스, 키보드, 터치, 게임패드, VR 컨트롤러의 API +* 🔊 **사운드** - Web Audio API를 이용한 3D 위치정보 사운드 +* 📦 **에셋** - [glTF 2.0](https://www.khronos.org/gltf/), [Draco](https://google.github.io/draco/), [Basis](https://github.com/BinomialLLC/basis_universal) 압축 기술을 이용한 비동기형 스트리밍 시스템 +* 📜 **스크립트** - TypeScript와 자바스크립트 지원 + +## 사용방법 + +여기에 아주 간단한 Hello World의 예가 있습니다. - 회전하는 큐브 + +```js +import * as pc from 'playcanvas'; + +const canvas = document.createElement('canvas'); +document.body.appendChild(canvas); + +const app = new pc.Application(canvas); + +// fill the available space at full resolution +app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW); +app.setCanvasResolution(pc.RESOLUTION_AUTO); + +// ensure canvas is resized when window changes size +window.addEventListener('resize', () => app.resizeCanvas()); + +// create box entity +const box = new pc.Entity('cube'); +box.addComponent('model', { + type: 'box' +}); +app.root.addChild(box); + +// create camera entity +const camera = new pc.Entity('camera'); +camera.addComponent('camera', { + clearColor: new pc.Color(0.1, 0.2, 0.3) +}); +app.root.addChild(camera); +camera.setPosition(0, 0, 3); + +// create directional light entity +const light = new pc.Entity('light'); +light.addComponent('light'); +app.root.addChild(light); +light.setEulerAngles(45, 0, 0); + +// rotate the box according to the delta time since the last frame +app.on('update', dt => box.rotate(10 * dt, 20 * dt, 30 * dt)); + +app.start(); +``` + +이 코드를 직접 시도하려면 [CodePen](https://codepen.io/playcanvas/pen/NPbxMj)를 클릭하세요. + +PlayCanvas 엔진을 기반으로 하는 로컬 개발 환경 설정에 대한 전체 가이드는 [여기](https://developer.playcanvas.com/user-manual/engine/standalone/)에서 찾을 수 있습니다. + +## 빌드 순서 + +[Node.js 18+](https://nodejs.org)가 설치 되어 있는지 확인합니다. 그 다음 필요한 Node.js 종속성을 모두 설치합니다. + +```sh +npm install +``` + +이제 다양한 빌드 옵션을 실행할 수 있습니다. + +| 명령어 | 설명 | 출력 위치 | +| --------------- | ----------------------------------------- | ---------- | +| `npm run build` | 모든 엔진 빌드 대상과 타입 선언을 빌드합니다 | `build` | +| `npm run docs` | 엔진 [API 참조 문서][docs]를 빌드합니다 | `docs` | + +## PlayCanvas 에디터 + +PlayCanvas 엔진은 HTML5 앱 및 게임을 만들기 위한 오픈 소스 엔진입니다.엔진 외에 [PlayCanvas 에디터](https://playcanvas.com/)가 있습니다. + +[![Editor](https://github.com/playcanvas/editor/blob/main/images/editor.png?raw=true)](https://github.com/playcanvas/editor) + +에디터 관련 버그나 문제는 [Editor's repo](https://github.com/playcanvas/editor)를 참조하십시오. + +[npm-badge]: https://img.shields.io/npm/v/playcanvas +[npm-url]: https://www.npmjs.com/package/playcanvas +[minzip-badge]: https://img.shields.io/bundlephobia/minzip/playcanvas +[minzip-url]: https://bundlephobia.com/result?p=playcanvas +[resolution-badge]: https://isitmaintained.com/badge/resolution/playcanvas/engine.svg +[open-issues-badge]: https://isitmaintained.com/badge/open/playcanvas/engine.svg +[isitmaintained-url]: https://isitmaintained.com/project/playcanvas/engine +[twitter-badge]: https://img.shields.io/twitter/follow/playcanvas.svg?style=social&label=Follow +[twitter-url]: https://twitter.com/intent/follow?screen_name=playcanvas +[docs]: https://api.playcanvas.com/modules/Engine.html diff --git a/README-zh.md b/README-zh.md index 17a74291d03..79ca03ad478 100644 --- a/README-zh.md +++ b/README-zh.md @@ -3,7 +3,8 @@ # PlayCanvas WebGL 游戏引擎 -[开发者站点](https://developer.playcanvas.com) | [例子](https://playcanvas.github.io) | [论坛](https://forum.playcanvas.com) | [博客](https://blog.playcanvas.com) + +[API 参考](https://api.playcanvas.com/modules/Engine.html) | [用户手册](https://developer.playcanvas.com) | [例子](https://playcanvas.github.io) | [论坛](https://forum.playcanvas.com) | [博客](https://blog.playcanvas.com) PlayCanvas 是一款使用 HTML5 和 WebGL 技术运行游戏以及其他 3D 内容的开源游戏引擎，PlayCanvas 以其独特的性能实现了在任何手机移动端和桌面浏览器端均可以流畅运行。 @@ -13,8 +14,10 @@ PlayCanvas 是一款使用 HTML5 和 WebGL 技术运行游戏以及其他 3D 内 [![Percentage of issues still open][open-issues-badge]][isitmaintained-url] [![Twitter][twitter-badge]][twitter-url] -[English](https://github.com/playcanvas/engine/blob/master/README.md) -[中文](https://github.com/playcanvas/engine/blob/master/README-zh.md) +[English](https://github.com/playcanvas/engine/blob/dev/README.md) +[中文](https://github.com/playcanvas/engine/blob/dev/README-zh.md) +[日本語](https://github.com/playcanvas/engine/blob/dev/README-ja.md) +[한글](https://github.com/playcanvas/engine/blob/dev/README-kr.md) ## 项目展示 @@ -22,7 +25,7 @@ PlayCanvas 是一款使用 HTML5 和 WebGL 技术运行游戏以及其他 3D 内 [![Seemore](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14705/319531/O4J4VU-image-25.jpg)](https://playcanv.as/p/MflWvdTW/) [![After The Flood](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/440410/98554E-image-25.jpg)](https://playcanv.as/p/44MRmJRU/) [![Casino](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/349824/U88HJQ-image-25.jpg)](https://playcanv.as/p/LpmXGUe6/) [![Swooop](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/4763/TKYXB8-image-25.jpg)](https://playcanv.as/p/JtL2iqIH/) [![Master Archer](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/415995/10A5A9-image-25.jpg)](https://playcanv.as/p/JERg21J8/) [![Flappy Bird](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/8/375389/23PRTL-image-25.jpg)](https://playcanv.as/p/2OlkUaxF/) -[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](http://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/) +[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/) 点击此链接查看更多案例： [PlayCanvas website](https://playcanvas.com/explore). @@ -38,7 +41,7 @@ PlayCanvas 是一款使用 HTML5 和 WebGL 技术运行游戏以及其他 3D 内 PlayCanvas 是一款优秀的全功能游戏引擎。 -- 🧊 **图形** - 基于 WebGL1&2 的超前 2D + 3D 图形引擎 +- 🧊 **图形** - 基于 WebGL2 的超前 2D + 3D 图形引擎 - 🏃 **动画** - 基于状态的强大动画功能，有效展现动画角色和随机场景属性 - ⚛️ **物理** - 一体化的 3D 刚体物理引擎 [ammo.js](https://github.com/kripken/ammo.js) - 🎮 **输入** - 支持鼠标，键盘，触控，游戏控制器以及众多 VR 控制器 API @@ -50,125 +53,73 @@ PlayCanvas 是一款优秀的全功能游戏引擎。 以下为一个简单的使用案例 - 实现一个旋转的立方体！ -```html - - - - - PlayCanvas Hello Cube - - - - - - - - - -``` - -想要自己动手试试？点击 [CodePen](https://codepen.io/playcanvas/pen/NPbxMj). - -## 如何搭建项目 - -确保已安装 [Node.js](https://nodejs.org) ，并安装 Node.js 相关依赖组件。 +```js +import * as pc from 'playcanvas'; - npm install +// 创建一个PlayCanvas应用 +const canvas = document.createElement('canvas'); +document.body.appendChild(canvas); -现在您就可以运行不同的搭建选项了： +const app = new pc.Application(canvas); -| Command | Description | Outputs | -| ----------------- | ----------------------------------------- | -------------------------------- | -| `npm run build` | Build release, debug and profiler engines | `build\playcanvas[.dbg/.prf].js` | -| `npm run tsd` | Build engine Typescript bindings | `build\playcanvas.d.ts` | -| `npm run docs` | Build engine [API reference docs][docs] | `docs` | +// 在全屏模式下填满可用空间 +app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW); +app.setCanvasResolution(pc.RESOLUTION_AUTO); -您也可以使用 PlayCanvas 的预搭建版本 +// 确保在窗口尺寸变化同时画布也同时改变其大小 +window.addEventListener('resize', () => app.resizeCanvas()); -最新的开发版本： +// 创建一个立方体 +const box = new pc.Entity('cube'); +box.addComponent('model', { + type: 'box' +}); +app.root.addChild(box); -- https://code.playcanvas.com/playcanvas-latest.js -- https://code.playcanvas.com/playcanvas-latest.min.js +// 创建一个摄像头 +const camera = new pc.Entity('camera'); +camera.addComponent('camera', { + clearColor: new pc.Color(0.1, 0.2, 0.3) +}); +app.root.addChild(camera); +camera.setPosition(0, 0, 3); -最新的稳定版本： +// 创建一个指向灯 +const light = new pc.Entity('light'); +light.addComponent('light'); +app.root.addChild(light); +light.setEulerAngles(45, 0, 0); -- https://code.playcanvas.com/playcanvas-stable.js -- https://code.playcanvas.com/playcanvas-stable.min.js +// 根据立方体的时间增量旋转立方体 +app.on('update', dt => box.rotate(10 * dt, 20 * dt, 30 * dt)); -特定引擎版本： - -- https://code.playcanvas.com/playcanvas-1.38.4.js -- https://code.playcanvas.com/playcanvas-1.38.4.min.js - -### 生成 Source Maps +app.start(); +``` -您可以在任何构建指令之后添加 `-- -m` 来生成 Source map 更好更方便地对引擎进行调试和排错： +想要自己动手试试？点击 [CodePen](https://codepen.io/playcanvas/pen/NPbxMj). - npm run build -- -m +基于 PlayCanvas 引擎设置本地开发环境的完整指南可以在[这里](https://developer.playcanvas.com/user-manual/engine/standalone/)找到。 -此条指令将会将结果输出到 `build/output/playcanvas.js.map` +## 如何搭建项目 -提示：在生成 source map 过程中，系统会忽略预处理器以防止其对过程产生影响。这意味着在生成 source map 的过程中，所有 debug 和 profiling 代码将会被包含在引擎构建中。 +确保已安装 [Node.js 18+](https://nodejs.org) ，并安装 Node.js 相关依赖组件。 -## 如何测试 +```sh +npm install +``` -PlayCanvas 使用 Karma 进行单元测试。您可以使用如下两种方式进行测试： +现在您就可以运行不同的搭建选项了： -| Command | Description | -| -------------------- | ------------------------------------------------------------------------------------ | -| `npm run test` | Runs unit tests on a built `playcanvas.js` | -| `npm run test:watch` | Re-runs unit tests when changes are detected - open http://localhost:9876/debug.html | +| 命令 | 描述 | 输出到 | +| --------------- | --------------------------- | ---------- | +| `npm run build` | 构建所有引擎构建目标和类型声明 | `build` | +| `npm run docs` | 构建引擎[API参考文档][docs] | `docs` | ## PlayCanvas 平台 PlayCanvas 引擎是一款可以基于浏览器的用于制作游戏以及 3D 可视化的开源引擎。除此之外，我们还开发了[PlayCanvas 开发平台](https://playcanvas.com/)， 为我们的用户提供了可视化编辑器，资源管理，代码编辑，代码托管以及发布等服务。 -[![Editor](https://github.com/playcanvas/editor/blob/master/images/editor.png?raw=true)](https://github.com/playcanvas/editor) +[![Editor](https://github.com/playcanvas/editor/blob/main/images/editor.png?raw=true)](https://github.com/playcanvas/editor) ## License @@ -178,9 +129,9 @@ The PlayCanvas Engine is released under the [MIT](https://opensource.org/license [npm-url]: https://www.npmjs.com/package/playcanvas [minzip-badge]: https://img.shields.io/bundlephobia/minzip/playcanvas [minzip-url]: https://bundlephobia.com/result?p=playcanvas -[resolution-badge]: http://isitmaintained.com/badge/resolution/playcanvas/engine.svg -[open-issues-badge]: http://isitmaintained.com/badge/open/playcanvas/engine.svg -[isitmaintained-url]: http://isitmaintained.com/project/playcanvas/engine +[resolution-badge]: https://isitmaintained.com/badge/resolution/playcanvas/engine.svg +[open-issues-badge]: https://isitmaintained.com/badge/open/playcanvas/engine.svg +[isitmaintained-url]: https://isitmaintained.com/project/playcanvas/engine [twitter-badge]: https://img.shields.io/twitter/follow/playcanvas.svg?style=social&label=Follow [twitter-url]: https://twitter.com/intent/follow?screen_name=playcanvas -[docs]: https://developer.playcanvas.com/en/api/ +[docs]: https://api.playcanvas.com/modules/Engine.html diff --git a/README.md b/README.md index cedca1890eb..f73f288f9bc 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,8 @@ # PlayCanvas WebGL Game Engine -[Docs](https://developer.playcanvas.com) | [Examples](https://playcanvas.github.io) | [Forum](https://forum.playcanvas.com) | [Blog](https://blog.playcanvas.com) + +[API Reference](https://api.playcanvas.com/engine/) | [User Manual](https://developer.playcanvas.com) | [Examples](https://playcanvas.github.io) | [Forum](https://forum.playcanvas.com) | [Blog](https://blog.playcanvas.com) PlayCanvas is an open-source game engine. It uses HTML5 and WebGL to run games and other interactive 3D content in any mobile or desktop browser. @@ -13,19 +14,18 @@ PlayCanvas is an open-source game engine. It uses HTML5 and WebGL to run games a [![Percentage of issues still open][open-issues-badge]][isitmaintained-url] [![Twitter][twitter-badge]][twitter-url] -[English](https://github.com/playcanvas/engine/blob/master/README.md) -[中文](https://github.com/playcanvas/engine/blob/master/README-zh.md) +[English](https://github.com/playcanvas/engine/blob/dev/README.md) +[中文](https://github.com/playcanvas/engine/blob/dev/README-zh.md) +[日本語](https://github.com/playcanvas/engine/blob/dev/README-ja.md) +[한글](https://github.com/playcanvas/engine/blob/dev/README-kr.md) ## Project Showcase -[Many games and apps](https://github.com/playcanvas/awesome-playcanvas#awesome-playcanvas- -) have been published using the PlayCanvas engine. Here is a small selection: +[Many games and apps](https://github.com/playcanvas/awesome-playcanvas) have been published using the PlayCanvas engine. Here is a small selection: [![Seemore](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14705/319531/O4J4VU-image-25.jpg)](https://playcanv.as/p/MflWvdTW/) [![After The Flood](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/440410/98554E-image-25.jpg)](https://playcanv.as/p/44MRmJRU/) [![Casino](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/14928/349824/U88HJQ-image-25.jpg)](https://playcanv.as/p/LpmXGUe6/) -[![Swooop](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/4763/TKYXB8-image-25.jpg)](https://playcanv.as/p/JtL2iqIH/) [![Master Archer](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/415995/10A5A9-image-25.jpg)](https://playcanv.as/p/JERg21J8/) [![Flappy Bird](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/8/375389/23PRTL-image-25.jpg)](https://playcanv.as/p/2OlkUaxF/) -[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](http://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/ ) - - +[![Swooop](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/4763/TKYXB8-image-25.jpg)](https://playcanv.as/p/JtL2iqIH/) [![dev Archer](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/415995/10A5A9-image-25.jpg)](https://playcanv.as/p/JERg21J8/) [![Flappy Bird](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/8/375389/23PRTL-image-25.jpg)](https://playcanv.as/p/2OlkUaxF/) +[![Car](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/347824/7ULQ3Y-image-25.jpg)](https://playcanv.as/p/RqJJ9oU9/) [![Star-Lord](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/333626/BGQN9H-image-25.jpg)](https://playcanv.as/p/SA7hVBLt/) [![Global Illumination](https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/4373/625081/6AB32D-image-25.jpg)](https://playcanv.as/p/ZV4PW6wr/ ) You can see more games on the [PlayCanvas website](https://playcanvas.com/explore). @@ -38,9 +38,9 @@ PlayCanvas is used by leading companies in video games, advertising and visualiz ## Features -PlayCanvas is a fully featured game engine. +PlayCanvas is a fully-featured game engine. -* 🧊 **Graphics** - Advanced 2D + 3D graphics engine built on WebGL 1 & 2. +* 🧊 **Graphics** - Advanced 2D + 3D graphics engine built on WebGL2 & WebGPU. * 🏃 **Animation** - Powerful state-based animations for characters and arbitrary scene properties * ⚛️ **Physics** - Full integration with 3D rigid-body physics engine [ammo.js](https://github.com/kripken/ammo.js) * 🎮 **Input** - Mouse, keyboard, touch, gamepad and VR controller APIs @@ -52,132 +52,82 @@ PlayCanvas is a fully featured game engine. Here's a super-simple Hello World example - a spinning cube! -```html - - - - - PlayCanvas Hello Cube - - - - - - - - - -``` +```js +import * as pc from 'playcanvas'; -Want to play with the code yourself? Edit it on [CodePen](https://codepen.io/playcanvas/pen/NPbxMj). +const canvas = document.createElement('canvas'); +document.body.appendChild(canvas); -## How to build - -Ensure you have [Node.js](https://nodejs.org) installed. Then, install all of the required Node.js dependencies: +const app = new pc.Application(canvas); - npm install - -Now you can run various build options: +// fill the available space at full resolution +app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW); +app.setCanvasResolution(pc.RESOLUTION_AUTO); -| Command | Description | Outputs | -|------------------------|-------------------------------------------|----------------------------------| -| `npm run build` | Build release, debug and profiler engines | `build\playcanvas[.dbg/.prf].js` | -| `npm run tsd` | Build engine Typescript bindings | `build\playcanvas.d.ts` | -| `npm run docs` | Build engine [API reference docs][docs] | `docs` | +// ensure canvas is resized when window changes size +window.addEventListener('resize', () => app.resizeCanvas()); -Pre-built versions of the engine are also available. +// create box entity +const box = new pc.Entity('cube'); +box.addComponent('model', { + type: 'box' +}); +app.root.addChild(box); -Latest development release (head revision of master branch): +// create camera entity +const camera = new pc.Entity('camera'); +camera.addComponent('camera', { + clearColor: new pc.Color(0.1, 0.2, 0.3) +}); +app.root.addChild(camera); +camera.setPosition(0, 0, 3); -* https://code.playcanvas.com/playcanvas-latest.js -* https://code.playcanvas.com/playcanvas-latest.min.js +// create directional light entity +const light = new pc.Entity('light'); +light.addComponent('light'); +app.root.addChild(light); +light.setEulerAngles(45, 0, 0); -Latest stable release: +// rotate the box according to the delta time since the last frame +app.on('update', dt => box.rotate(10 * dt, 20 * dt, 30 * dt)); -* https://code.playcanvas.com/playcanvas-stable.js -* https://code.playcanvas.com/playcanvas-stable.min.js - -Specific engine versions: - -* https://code.playcanvas.com/playcanvas-1.38.4.js -* https://code.playcanvas.com/playcanvas-1.38.4.min.js - -### Generate Source Maps +app.start(); +``` -To build the source map to allow for easier engine debugging, you can add `-- -m` to any engine build command. For example: +Want to play with the code yourself? Edit it on [CodePen](https://codepen.io/playcanvas/pen/NPbxMj). - npm run build -- -m +A full guide to setting up a local development environment based on the PlayCanvas Engine can be found [here](https://developer.playcanvas.com/user-manual/engine/standalone/). -This will output to `build/output/playcanvas.js.map` +## How to build -Note: The preprocessor is ignored when generating the source map as it breaks the mapping. This means that all debug and profiling code is included in the engine build when generating the source map. +Ensure you have [Node.js 18+](https://nodejs.org) installed. Then, install all of the required Node.js dependencies: -## How to run tests +```sh +npm install +``` -PlayCanvas uses of Karma for unit testing. There are two ways of running the tests: +Now you can run various build options: -| Command | Description | -|------------------------|---------------------------------------------------------------------------------------| -| `npm run test` | Runs unit tests on a built `playcanvas.js` | -| `npm run test:watch` | Re-runs unit tests when changes are detected - open http://localhost:9876/debug.html | +| Command | Description | Outputs To | +| --------------- | ---------------------------------------------- | ---------- | +| `npm run build` | Build all engine flavors and type declarations | `build` | +| `npm run docs` | Build engine [API reference docs][docs] | `docs` | ## PlayCanvas Editor -The PlayCanvas Engine is an open source engine which you can use to create HTML5 apps/games. In addition to the engine, we also make the [PlayCanvas Editor](https://playcanvas.com/): +The PlayCanvas Engine is an open-source engine that you can use to create HTML5 apps/games. In addition to the engine, we also make the [PlayCanvas Editor](https://playcanvas.com/): -[![Editor](https://github.com/playcanvas/editor/blob/master/images/editor.png?raw=true)](https://github.com/playcanvas/editor) +[![Editor](https://github.com/playcanvas/editor/blob/main/images/editor.png?raw=true)](https://github.com/playcanvas/editor) -For Editor related bugs and issues, please refer to the [Editor's repo](https://github.com/playcanvas/editor). +For Editor-related bugs and issues, please refer to the [Editor's repo](https://github.com/playcanvas/editor). [npm-badge]: https://img.shields.io/npm/v/playcanvas [npm-url]: https://www.npmjs.com/package/playcanvas [minzip-badge]: https://img.shields.io/bundlephobia/minzip/playcanvas [minzip-url]: https://bundlephobia.com/result?p=playcanvas -[resolution-badge]: http://isitmaintained.com/badge/resolution/playcanvas/engine.svg -[open-issues-badge]: http://isitmaintained.com/badge/open/playcanvas/engine.svg -[isitmaintained-url]: http://isitmaintained.com/project/playcanvas/engine +[resolution-badge]: https://isitmaintained.com/badge/resolution/playcanvas/engine.svg +[open-issues-badge]: https://isitmaintained.com/badge/open/playcanvas/engine.svg +[isitmaintained-url]: https://isitmaintained.com/project/playcanvas/engine [twitter-badge]: https://img.shields.io/twitter/follow/playcanvas.svg?style=social&label=Follow [twitter-url]: https://twitter.com/intent/follow?screen_name=playcanvas -[docs]: https://developer.playcanvas.com/en/api/ +[docs]: https://api.playcanvas.com/modules/Engine.html diff --git a/build.mjs b/build.mjs new file mode 100644 index 00000000000..e7e88ad56d6 --- /dev/null +++ b/build.mjs @@ -0,0 +1,45 @@ +/** + * Build helper scripts + * Usage: node build.mjs [options] -- [rollup options] + * + * Options: + * target[:][:][:] - Specify the target + * - moduleFormat (esm, umd) + * - buildType (release, debug, profiler, min) + * - bundleState (unbundled, bundled) + * Example: target:esm:release:bundled + * + * treemap - Enable treemap build visualization (release only). + * treenet - Enable treenet build visualization (release only). + * treesun - Enable treesun build visualization (release only). + * treeflame - Enable treeflame build visualization (release only). + */ + +import { execSync } from 'child_process'; + +const args = process.argv.slice(2); + +const ENV_START_MATCHES = [ + 'target', + 'treemap', + 'treenet', + 'treesun', + 'treeflame' +]; + +const env = []; +for (let i = 0; i < args.length; i++) { + if (ENV_START_MATCHES.some(match => args[i].startsWith(match)) && args[i - 1] !== '--environment') { + env.push(`--environment ${args[i]}`); + args.splice(i, 1); + i--; + continue; + } +} + +const cmd = `rollup -c ${args.join(' ')} ${env.join(' ')}`; +try { + execSync(cmd, { stdio: 'inherit' }); +} catch (e) { + console.error(e.message); +} diff --git a/conf-api.json b/conf-api.json deleted file mode 100644 index 8853241f160..00000000000 --- a/conf-api.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "plugins": [ - "plugins/markdown" - ], - "recurseDepth": 10, - "source": { - "include": ["src"], - "includePattern": ".+\\.js(doc|x)?$", - "excludePattern": "(^|\\/|\\\\)_" - }, - "sourceType": "module", - "tags": { - "allowUnknownTags": true, - "dictionaries": ["jsdoc","closure"] - }, - "templates": { - "cleverLinks": false, - "monospaceLinks": false - }, - "opts": { - "destination": "docs", - "encoding": "utf8", - "recurse": true, - "template": "./node_modules/@playcanvas/jsdoc-template" - } -} \ No newline at end of file diff --git a/conf-tsd.json b/conf-tsd.json deleted file mode 100644 index b9ce3c2bb14..00000000000 --- a/conf-tsd.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "source": { - "include": ["src"] - }, - "opts": { - "destination": "build", - "outFile": "playcanvas.d.ts", - "recurse": true, - "template": "node_modules/tsd-jsdoc/dist" - } -} diff --git a/eslint.config.mjs b/eslint.config.mjs new file mode 100644 index 00000000000..8e59750a10c --- /dev/null +++ b/eslint.config.mjs @@ -0,0 +1,70 @@ +import playcanvasConfig from '@playcanvas/eslint-config'; +import globals from 'globals'; + +// Extract or preserve existing JSDoc tags +const jsdocRule = playcanvasConfig.find( + config => config.rules && config.rules['jsdoc/check-tag-names'] +); +const existingTags = jsdocRule?.rules['jsdoc/check-tag-names'][1]?.definedTags || []; + +export default [ + ...playcanvasConfig, + { + files: ['**/*.js', '**/*.mjs'], + languageOptions: { + ecmaVersion: 2022, + sourceType: 'module', + globals: { + ...globals.browser, + ...globals.mocha, + ...globals.node, + 'Ammo': 'readonly', + 'earcut': 'readonly', + 'opentype': 'readonly', + 'pc': 'readonly', + 'TWEEN': 'readonly', + 'twgsl': 'readonly', + 'webkitAudioContext': 'readonly' + } + }, + rules: { + 'import/order': 'off', + 'jsdoc/check-tag-names': [ + 'error', + { + // custom mjs script tags to not error on, add them to those from parent config + definedTags: [...new Set([...existingTags, 'range', 'step', 'precision'])] + } + ] + } + }, + { + files: ['scripts/**/*.js'], + rules: { + 'no-var': 'off' + } + }, + { + files: ['scripts/**/*.mjs'], + rules: { + 'jsdoc/no-defaults': 'off', // Attributes use default values + 'import/no-unresolved': 'off' // PlayCanvas is not installed for scripts + } + }, + { + files: ['test/**/*.mjs'], + rules: { + 'import/order': 'error', + 'no-unused-expressions': 'off', + 'prefer-arrow-callback': 'off' // Mocha uses function callbacks + } + }, + { + ignores: [ + 'examples/lib/*', + 'scripts/textmesh/*.min.js', + 'src/polyfill/*', + 'scripts/spine/*' + ] + } +]; diff --git a/examples/.gitignore b/examples/.gitignore new file mode 100644 index 00000000000..6de0845310c --- /dev/null +++ b/examples/.gitignore @@ -0,0 +1,5 @@ +# Prettier config +.prettierrc + +# Cache directory +cache \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index c5f193e5216..6ece9a36d9f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,118 +6,169 @@ A selection of simple examples to get you up and running See them running live -## Local development +## Local examples browser development +This section covers how to locally develop the examples browser application. For information on how to develop individual examples please see the following section. + Ensure you have Node.js installed. Then, install all of the required Node.js dependencies: ``` npm install ``` -Now run the following two commands in two separate terminals: +Now run the following command: ``` -npm run build:watch +npm run develop ``` -and +Visit the url mentioned in your terminal to view the examples browser. + +You can also run the examples browser with a specific version of the engine by running the following command: + ``` -npm run serve +ENGINE_PATH=../build/playcanvas.mjs npm run develop ``` -Visit [http://localhost:5000]() to view the examples browser. -To create the side bar thumbnails run the following script: +Where `../build/playcanvas.mjs` is the path to the ESM version of the engine. + +Or directly from the source: + ``` -npm run thumbnails +ENGINE_PATH=../src/index.js npm run develop ``` -### Local engine development -By default, the local build uses whichever version of PlayCanvas is listed in the package.json file. If you'd like to use the locally built version of PlayCanvas in the engines build directory you can replace the `npm run build:watch` script above with `npm run local` or `npm run local:dbg` for the debug version. +## Creating an example -By default, example code is executed as an anonymous function in the browser (in order to support live code editing). However this limits the usefulness of debugging tools as the callstack for the example code is obscured. To run examples with a full callstack, allowing line by line debugging of an example, you can use the debug path for each example. Where `/#/misc/hello-world` becomes `/#/debug/misc/hello-world`. A full list of debug paths can be found at [http://localhost:5000/debug-directory](). +The available examples are written as classes in JavaScript under the paths `./src/examples//.example.mjs`. +To create a new example you can copy any of the existing examples as a template. -## Creating an example +Each example consists of two modules to define its behavior: -The available examples are written as classes in TypeScript under the paths `./src/examples/\/\.tsx. -To create a new example you can copy any of the existing examples as a template and update its path. +### `.example.mjs` -Each example extends the `Example` parent class and can implement three methods to define its functionality: +```js +import * as pc from 'playcanvas'; -### `example` function -```tsx -import * as pc from 'playcanvas/build/playcanvas.js'; -example(canvas: HTMLCanvasElement) { - const app = new pc.Application(canvas, {}); -} -``` -This is the only function that's required to run an example. The code defined in this function is executed each time the example play button is pressed. It takes the example's canvas element as its first argument and usually begins by creating a new PlayCanvas application using that canvas. - -### `load` function -You can define a set of PlayCanvas assets to load into your application using this function. The function should return a set of Loader React components: -```tsx -import React from 'react'; -import { AssetLoader } from '../../app/helpers/loader'; -load() { - return <> - - - <>; -} +const canvas = /** @type {HTMLCanvasElement} */ (document.getElementById('application-canvas')); +window.focus(); + +const app = new pc.Application(canvas, {}); + +export { app }; ``` -As assets are loaded using React, be sure to import React into any example that is loading assets. -Assets and scripts present in the `./assets` and `../scripts` directories will be available to examples under the `static/` path. -Each asset you load will be made available to the `example` function you write as the second parameter and will already be in the loaded state. -```tsx -example(canvas: HTMLCanvasElement, assets: { statue: pc.Asset, firstPersonCamScript: pc.Asset }) { - const app = new pc.Application(canvas, {}); - // this will log true - console.log(assets.statue.loaded); -} +This is the only file that's required to run an example. The code defined in this function is executed each time the example play button is pressed. It takes the example's canvas element from the DOM and usually begins by creating a new PlayCanvas `Application` or `AppBase` using that canvas. + +Examples can also contain comments which allow you to define the default configuration for your examples as well as overrides to particular settings such as `deviceType`. Check the possible values to set in `ExampleConfig` in `scripts/utils.mjs` file for the full list. + +```js +// @config DESCRIPTION This is a description +// @config HIDDEN +// @config ENGINE performance +// @config NO_DEVICE_SELECTOR +// @config NO_MINISTATS +// @config WEBGPU_DISABLED +// @config WEBGL_DISABLED +import * as pc from 'playcanvas'; +... ``` -Be sure to correctly define the type of the assets parameter to list each asset you're loading into the example. +You can load external scripts into an example using the `loadES5` function as follows: -You can also load external scripts into an example using the `ScriptLoader` React component as follows: -```tsx -import React from 'react'; -import { ScriptLoader } from '../../app/helpers/loader'; -load() { - return <> - - <>; -} +```js +import { loadES5 } from 'examples/utils'; + +const CORE = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/core@2.3.6/dist/dist.min.js'); +const DRACO = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/draco@2.3.6/dist/dist.min.js'); ``` -Each script will be made available as a parameter of the example function as an esModule using the name it was given and therefore any scripts should be defined in the examples function signature as follows: -```tsx -example(canvas: HTMLCanvasElement, TWEEN: any) { - const app = new pc.Application(canvas, {}); - console.log(TWEEN); -} + +However, depending on external URL's is maybe not what you want as it breaks your examples once your internet connection is gone - you can simply import modules directly as follows: + +```js +import confetti from "https://esm.sh/canvas-confetti@1.6.0" ``` -### `controls` function -This function allows you to define a set of PCUI based interface which can be used to display stats from your example or provide users with a way of controlling the example. -```tsx -import Button from '@playcanvas/pcui/Button/component'; -controls(data: any) { - return <> -