Skip to content

contributing.md

Latest commit

 

History

History
170 lines (127 loc) · 7.59 KB

contributing.md

File metadata and controls

170 lines (127 loc) · 7.59 KB

Orillusion Contributing Guide

Hi! I'm really excited that you are interested in contributing to Orillusion. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Issue Reporting Guidelines

  • Welcome to use Github to report a issues, request a feature, or ask a question

Pull Request Guidelines

  • Don't directly send PR to main branch, unless it's a urgent bug fix/patch.

  • Checkout a feature branch from a dev based branch, e.g. dev, and merge back against that branch.

  • Make sure to tick the "Allow edits from maintainers" box. This allows us to directly make minor edits / refactors and saves a lot of time.

  • If adding a new feature:

    • Add accompanying unit test or sample case.
    • Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it.

  • If fixing a bug:

    • If you are resolving a special issue, add (fix #xxxx[,#xxxx]) (#xxxx is the issue id) in your PR title for a better release log, e.g. update entities encoding/decoding (fix #3899).
    • Provide a detailed description of the bug in the PR. Live sample/demo preferred.

  • It's OK to have multiple small commits as you work on the PR - GitHub can automatically squash them before merging.

  • Make sure CI tests pass!

  • Commit messages must follow the commit message convention so that changelogs can be automatically generated.

Development Setup

Node.js version 16+, and PNPM version 7+ is perferred.

First, you need to fork repo Then, clone your forked repo

$ git clone git@github.com:XXX/orillusion.git
$ cd orillusion
$ git checkout dev # `dev` branch is perfered to start your development

If you need to run samples, you may need to init the assets submodule to load models, images and other resources:

$ git submodule update --init # init /public assets folder, it may take a long time due to large file size

After cloning the repo, run:

$ pnpm i # install all deps of the project

If you don't need electron/CI test in local, you can set ELECTRON_SKIP_BINARY_DOWNLOAD env to skip electron downloading process

$ ELECTRON_SKIP_BINARY_DOWNLOAD=1 pnpm i # install deps without downloading electron binary

A high level overview of main tools used:

Write New Samples

  1. create new entry ts in /samples/xxx/Sample_xxx.ts, the file name should be self-explanatory and start with Sample_. If there is no folder/category for your sample, create new one.

  2. write your scene code, take /samples/base/Sample_Transform.ts as a starter template/example.

  3. Coding rules:

    1. import core modules from @orillusion/core, e.g. Engine3D, Scene3D, Object3D, ....
    2. import plugins/extentions from @orillusion/xxx, e.g. @orillusion/stats, @orillusion/particle, @orillusion/physics....
    3. perfer using Top-level await to initialize the Engine3D and other async APIs.
    4. perfer embedding all functions/classes/modules into one single ts file.
    5. perfer using dat.gui to control your scene parameters.
    6. write comments as much as possible to make your code more readable and self-documented.

  4. If your sample requires local files, e.g. gltf models, images, we perfer you upload them to a public filehosting service, e.g. github pages, cloudflare CDNs, npmjs, AWS S3, Aliyun OSS, etc. Then use the public URLs to import them in your samples. Otherwise, you can add files to the /public folder and make PRs to our assets repo so that you can import files directly from the / path.

Scripts

Start a Dev server

After install all dependenceies of the project, just run pnpm run dev to boot up a dev environment locally, with live relaod of the soure code.

$ pnpm run dev

After executing the above command, visit http://localhost:8000 and try live samples from /samples

Build production libs

To build a production package:

$ pnpm run build

After executing the above command, the production libs (orillusion.es.js and orillusion.umd.js) will be generated in dist folder, along with all types *.d.ts in dist/src subfolder.

Unit Test

To start an auto unit tests:

$ pnpm run test

This will start an electron window to run all tests in test folder.

If you need to test in a docker/linux enviroment without GPU drivers:

$ pnpm run test:ci

This will force Electron to use a CPU based software Vulkan driver to process all tests with WebGPU APIs

API docs

To generate API docs:

$ pnpm run docs # generate all docs, including core and packages
$ pnpm run docs:core # core docs only

All md docs will be generated in docs folder.

Project Structure

A overview of project structure:

├─ 📂 node_modules/       # Dependencies
│  ├─ 📁 @webgpu          # WebGPU types for TS
│  └─ 📁 ...              # Other dependencies (TypeScript, Vite, etc.)
├─ 📂 src/                # @orillusion/core source
│  ├─ 📄 index.ts         # The entry root, export all modules from /src
│  └─ 📁 ...              # The core source files in sub category
├─ 📂 packages/           # @orillusion/xxx extensions
│  ├─ 📁 ammo             # Archive for Ammo.js
│  ├─ 📁 debug            # Internal debug lib based on dat.gui
│  ├─ 📁 draco            # Archive for draco_decoder.js
│  ├─ 📁 media-extention  # Media components for Orillusion
│  ├─ 📁 physics          # physics component for Orillusion, powerd by Ammo.js
│  └─ 📁 stats            # A simple performance stats component
│  └─ 📁 ...              # Others
├─ 📂 samples/            # Live samples
│  ├─ 📄 index.ts         # A entry mune to hold all samples in /samples
│  └─ 📁 ...              # Samples to test each sub category
├─ 📂 test/               # Unit tests
│  ├─ 📄 index.ts         # Entry mune to hold all tests in /test
│  ├─ 📄 util.ts          # test libs
│  ├─ 📁 ci               # main entry for electron
│  └─ 📁 ...              # Unit tests in each sub category
├─ 📄 .gitignore          # Ignore certain files in git repo
├─ 📄 index.html          # Dev index page
├─ 📄 LICENSE             # MIT
├─ 📄 package.json        # Node package file
├─ 📄 tsconfig.json       # TS configuration file
├─ 📄 vite.config.js      # vite configuration file
└─ 📄 README.md           # Read Me!

Welcome to submit PRs to extend @orillusion packages