diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 765b74e0674..55129c0e681 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -32,7 +32,9 @@ Simple code is always better. Modular (horizontal dependencies) code is easier t For example, use "Initialize" instead of "Initialise", and "color" instead of "colour". -### Whitelisted ES6+ features: +### Permitted ES6+ features: + +You may use the following JavaScript language features in the engine codebase: * [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let) * [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) @@ -42,6 +44,8 @@ For example, use "Initialize" instead of "Initialise", and "color" instead of "c * [Default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) * [Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) * [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) ### Opening braces should be on the same line as the statement diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 867890d4826..007a54e332a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,7 +14,7 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js 12.x - uses: actions/setup-node@v2.1.5 + uses: actions/setup-node@v2.4.1 with: node-version: 12.x - name: Install dependencies @@ -29,7 +29,7 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js 12.x - uses: actions/setup-node@v2.1.5 + uses: actions/setup-node@v2.4.1 with: node-version: 12.x - name: Install dependencies @@ -44,7 +44,7 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js 12.x - uses: actions/setup-node@v2.1.5 + uses: actions/setup-node@v2.4.1 with: node-version: 12.x - name: Install dependencies @@ -59,7 +59,7 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js 12.x - uses: actions/setup-node@v2.1.5 + uses: actions/setup-node@v2.4.1 with: node-version: 12.x - name: Install dependencies diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 00000000000..666132e9a32 --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,71 @@ +# 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/.gitignore b/.gitignore index cdb438d3510..ebc034b381a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ /docs node_modules/ .idea/ +.vscode/ npm-debug.log .java-version release.py +examples/node_modules +examples/dist diff --git a/README-ja.md b/README-ja.md new file mode 100644 index 00000000000..99e86dba940 --- /dev/null +++ b/README-ja.md @@ -0,0 +1,181 @@ +
+ + + +# PlayCanvas WebGL Game Engine +[Docs](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) + +## ショーケース + +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/) [![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/ ) + + +他のゲームは[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の例です。 + +```html + + + + + PlayCanvas Hello Cube + + + + + + + + + +``` +このコードを自分で試すには[CodePen](https://codepen.io/playcanvas/pen/NPbxMj)をクリックします。 + +## ビルドの手順 + +Node.jsがインストールされていることを確認します。 +次に、必要なNode.jsの依存関係をすべてインストールします。 + + npm install + +これで、様々なオプションでビルドを実行できるようになりました。 + +| コマンド | 説明 | 出力ファイル | +|------------------------|-------------------------------------------|----------------------------------| +| `npm run build` | リリース用、デバッグ用、プロファイラー用エンジンをビルドする | `build\playcanvas[.dbg/.prf].js` | +| `npm run tsd` | TypeScript型定義ファイルをビルドする | `build\playcanvas.d.ts` | +| `npm run docs` | [APIリファレンス][docs] をビルドする| `docs` | + + +また、ビルド済みのエンジンも利用できます。 + +最新版のビルド(masterブランチのHEADリビジョン) + +* https://code.playcanvas.com/playcanvas-latest.js +* https://code.playcanvas.com/playcanvas-latest.min.js + +最新安定版のビルド +* https://code.playcanvas.com/playcanvas-stable.js +* https://code.playcanvas.com/playcanvas-stable.min.js + +特定のバージョンのビルド +* https://code.playcanvas.com/playcanvas-1.38.4.js +* https://code.playcanvas.com/playcanvas-1.38.4.min.js + +### Generate Source Maps + +エンジンのデバッグがしやすいようにソースマップを構築するには、任意のエンジン構築コマンドに`-- -m`を追加します。例えば、以下のようになります。 + + + npm run build -- -m + +これにより`build/output/playcanvas.js.map`が出力されます。 + +注意: ソースマップを生成する際、プリプロセッサはマッピングを破壊するため無視されます。つまり、ソースマップの生成時には、すべてのデバッグコードとプロファイリングコードがエンジンのビルドに含まれます。 + +## テスト + +PlayCanvasではユニットテストにKarmaを使用しています。テストを実行する方法は2つあります。 + +| コマンド | 説明 | +|------------------------|---------------------------------------------------------------------------------------| +| `npm run test` | ビルドされた `playcanvas.js` に対してユニットテストを実行します。 | +| `npm run test:watch` | 変更が検出されたときにユニットテストを再実行する - open http://localhost:9876/debug.html | + +## PlayCanvasエディター + +PlayCanvas エンジンは、HTML5 アプリやゲームを作成するためのオープンソースのエンジンです。エンジンに加えて、[PlayCanvasエディター](https://playcanvas.com/)があります。 + +[![Editor](https://github.com/playcanvas/editor/blob/master/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]: 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 +[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/ \ No newline at end of file diff --git a/README-zh.md b/README-zh.md index 17a74291d03..d80ebfe9167 100644 --- a/README-zh.md +++ b/README-zh.md @@ -15,6 +15,7 @@ PlayCanvas 是一款使用 HTML5 和 WebGL 技术运行游戏以及其他 3D 内 [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) ## 项目展示 diff --git a/README.md b/README.md index 3c2140b060c..272239f9f71 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ PlayCanvas is an open-source game engine. It uses HTML5 and WebGL to run games a [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) ## Project Showcase @@ -34,7 +35,7 @@ You can see more games on the [PlayCanvas website](https://playcanvas.com/explor ## Users PlayCanvas is used by leading companies in video games, advertising and visualization such as: -**Animech, Arm, Disney, Facebook, IGT, King, Miniclip, Leapfrog, Mozilla, Nickelodeon, Nordeus, PikPok, PlaySide Studios, Polaris, Product Madness, Samsung, Snap, Spry Fox, Zeptolab, Zynga** +**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** ## Features diff --git a/examples/README.md b/examples/README.md index 9b0e8b0e379..d5e50b5db7a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -5,3 +5,127 @@ A selection of simple examples to get you up and running See them running live + +## Local development +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: +``` +npm run build:watch +``` +and +``` +npm run serve +``` +Visit [http://localhost:5000]() to view the examples browser. + +To create the side bar thumbnails run the following script: +``` +npm run thumbnails +``` + +Please note that the examples app requires a built version of the engine to be present in the engine repo within the `../build` folder. If you haven't already done so, run `npm install` followed by `npm run build` in the engine repo. + +### Debug and performance engine development +By default, the examples app uses the local version of the playcanvas engine. If you'd like to use the debug or performance versions of the engine instead, you can run `npm run build:debug` or `npm run build:profiler`. + +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](). + +## Creating an example + +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. + +Each example extends the `Example` parent class and can implement three methods to define its functionality: + +### `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 <> + + + <>; +} +``` +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); +} +``` + +Be sure to correctly define the type of the assets parameter to list each asset you're loading into the example. + +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 <> + + <>; +} +``` +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); +} +``` + +### `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 <> +