Improve engine repo readme (#12583)

* Improve engine repo readme

* Add ts coding style reference and improve contribution guide

* Temporary remove screen shots section

* minor change
This commit is contained in:
pandamicro
2022-09-01 11:30:09 +08:00
committed by GitHub
parent 1a650b458d
commit 5746790a78
2 changed files with 665 additions and 16 deletions
+53 -16
View File
@@ -29,28 +29,43 @@
# Engine for Cocos Creator
![image](https://user-images.githubusercontent.com/1503156/111035862-53548000-8457-11eb-8e8b-52d854caf627.png)
**Cocos Creator is the new generation of game development tool in Cocos family, it brings a complete set of 3D and 2D features while providing an intuitive, low cost and collaboration friendly workflow to game developers.** Cocos Engine is the runtime framework for Cocos Creator editor.
Cocos Engine is the framework for Cocos Creator editor. Cocos Creator is the new generation of game development tool in Cocos family, it brings a complete set of 3D features and provides an intuitive, low cost and collaboration friendly workflow to game developers.
![image](https://www.cocos.com/wp-content/uploads/2022/08/13f41f1c975e8255fdc06f59597b9546-7.png)
Cocos Creator inherited many good qualities and cool features from its previous versions, such as cross-platform support including instant gaming platforms like WeChat mini game, asset management, powerful animation editing, etc. Furthermore, Cocos Creator has pushed our technology to a whole new level. Our GFX implementation is designed to adapt to the latest graphic backend APIs, it already supports WebGL 2 and can be seamlessly fall back to WebGL 1, it will support Vulkan and Metal in the native build. The material system is built on our own effect format which uses GLSL 300 and can be easily adapted to lower version on low end devices. Developers can produce high performance, extremely expressive shaders with good compatibility. Along with physical based camera and lighting, high level game graphic can be easily achieved. Our pure GPU driven skeleton animation also make sure your game runs as smooth as possible. Besides all these exciting features, Cocos Creator have builtin physics support, terrain editing support, visual effect editing, ui system, TypeScript support, instant preview etc.
Cocos Creator inherited many good qualities and cool features from its previous versions, such as high performance low level C++ implementation, intuitive editor, cross-platform support. It supports native platforms, web platforms and rapidly expanding instant gaming platforms, including Windows, Mac, iOS, Android, HarmonyOS, Web, Facebook Instant Games, WeChat Mini Game and TikTok Mini Games.
Furthermore, Cocos Creator has pushed the engine technology to a whole new level for high performance with scalability on various platforms, full extensibility and easy development.
1. **Modern Graphics**: The GFX implementation is designed to adapt to the modern graphics APIs, it uses Vulkan on Windows and Android, Metal on Mac OS and iOS, WebGL on Web platform.
2. **High Performance**: The runtime engine is built with half C++ and half TypeScript, low level infrastructure, native platform adaptation, renderer and scene management are all written in C++ to ensure high runtime performance. We continue to move heavy lifting work to native as much as possible.
3. **Customizable Render Pipeline**: The render pipeline is designed to be fully customizable, it has supported the builtin forward and deferred render pipeline across all platforms. Developers can customize their own render pipeline following the same approach.
4. **Extensible Surface Shader**: The material system is built on Cocos effect format which uses GLSL 300, the shader programs will be converted to suitable runtime format automatically. The surface shader permit to fully customize the surface material while ensuring universal lighting model.
5. **Physically Based Rendering (PBR)**: The standard effect adopts physically based rendering, along with the physically based camera and the lighting based on physical metrics, developers can easily achieve realistic and seamless rendering results across different environment.
6. **Easy TypeScript API**: The user level API set is provided in TypeScript, along with the powerful VSCode editor, development with Cocos Creator is incredibly efficient.
Besides all these highlights, Cocos Creator also provides builtin animation system, physics system, particle system, terrain editing support, complex UI system, instant preview etc.
![image](https://user-images.githubusercontent.com/1503156/111037166-f27c7600-845d-11eb-988f-4c2c8b5c7321.png)
This repo is the engine part of Cocos Creator, it's mainly written in TypeScript and support users to use TypeScript or ES6 to write game logics. In addition, the `native` directory provides the underlying implementation of the engine on native platforms. The engine itself is mostly self-contained, with full-fledged runtime modules including lighting, material, particle, animation, physical, UI, terrain, sound, resource and scene-graph management, etc. It supports both native and web platforms, including Windows, Mac, iOS, Android, HarmonyOS, Web. What's more exciting is that it supports rapidly expanding instant gaming platforms like WeChat Mini Game and Facebook Instant Games.
This open source repository is the runtime engine of Cocos Creator, the engine is naturally integrated within Cocos Creator, designed to only be the essential runtime library and not to be used independently.
The engine is naturally integrated within Cocos Creator, designed to only be the essential runtime library and not to be used independently.
## Development and Contribution Notice
## Developer
Cocos Creator engine is open source and welcomes community participation, for open source engine development with Cocos Creator editor, you should fork this repository and setup [custom engine](https://docs.cocos.com/creator/manual/en/advanced-topics/engine-customization.html) in the editor.
### Prerequisite
- Install [node.js v9.11.2 +](https://nodejs.org/)
- Install [gulp-cli v2.3.0 +](https://github.com/gulpjs/gulp/tree/master/docs/getting-started)
### Clone
Clone this repository into your local environment.
### Install
In the cloned repo, run the following command to setup dev environment:
In the cloned engine folder, run the following command to setup development environment:
```bash
# download & build engine dependencies
@@ -64,24 +79,46 @@ This is all you have to do to setup engine development environment.
- If running inside Cocos Creator, the engine will automatically compile and build after the editor window is opened. For more instructions on modifying the engine in Cocos Creator, please refer to [Engine Customization Workflow](https://docs.cocos.com/creator/manual/en/advanced-topics/engine-customization.html).
- Outside the editor, you need to run the following command to build:
```bash
npm run build
```
```bash
npm run build
```
Please refer to [native readme](native/README.md) if want to develop native applications.
Please refer to [native readme](native/README.md) if you want to develop native applications.
### Contribution
You can contribute to the Cocos Creator open source engine in many ways, they are very much appreciated:
1. Report bug or feature requests by [creating an issue](https://github.com/cocos/cocos-engine/issues/new/choose).
2. Participate discussions in the [issues](https://github.com/cocos/cocos-engine/issues/).
3. Create a pull request if you have fixed or improved anything, implemented any features.
4. Improve the documentations with pull request to the [usage documentation repository](https://github.com/cocos/cocos-docs).
5. Help other developers in our [Forum](https://discuss.cocos2d-x.org/c/creator).
### Contribution notice
If you are trying to make a pull request, there are some requirements that must be met so that your pull request can be accepted:
1. Follow our [Cpp Coding Style Guide](./docs/CPP_CODING_STYLE.md) and [TypeScript Coding Style Reference](./docs/TS_CODING_STYLE.md).
2. Try to integrate ESLint and [CPP auto fix tools](./docs/CPP_LINTER_AUTOFIX_GUIDE.md) in your coding environment.
3. Link related issues or discussions in your pull request and clearly state the purpose of your pull request.
4. Pass all automatic continuous integration tests.
5. Request file owner or engine developers to review your pull request.
6. Get one valid approval from the engine architects.
## Example Project
- [Example Cases](https://github.com/cocos/cocos-example-projects): Simple yet expressive demo scenes for baseline testing and topic-specific case study.
- [Mind Your Step 3D](https://github.com/cocos/cocos-tutorial-mind-your-step): Beginner's step-by-step tutorial project repo.
- [UI Demo](https://github.com/cocos/cocos-example-ui): Use cases for various kinds of UI components.
- [Test Cases](https://github.com/cocos/cocos-test-projects): Unit test scenes for every engine module.
- [Example Cases](https://github.com/cocos/cocos-example-projects): Simple yet expressive demo scenes for baseline testing and topic-specific case study.
- [Awesome Cocos](https://github.com/cocos/awesome-cocos): You can find out other useful tools and show cases here.
## Links
- [Official site](https://www.cocos.com/products#CocosCreator)
- [Download](https://www.cocos.com/creator)
- [Official site](https://www.cocos.com/)
- [Download](https://www.cocos.com/en/creator/download)
- [Documentation](https://docs.cocos.com/creator/manual/en/)
- [API References](https://docs.cocos.com/creator/api/en/)
- [Projects and road map](https://github.com/orgs/cocos/projects?query=is%3Aopen&type=new)
- [Forum](https://discuss.cocos2d-x.org/c/creator)
- [Road Map](https://trello.com/b/JWVRRxMG/cocos-creator-roadmap)
- Discord community: Search for Cocos in the Discover panel of Discord.
+612
View File
@@ -0,0 +1,612 @@
# TypeScript and JavaScript Coding Style Reference
The following are some coding style rules for TypeScript and JavaScript we concluded during the development of Cocos Creator. It's important to mention that it's based on some basic conventions and our practices. Due to the fact that TypeScript compiler and JavaScript engine is keep evolving rapidly, we try to make the references quite simple.
There are also some project related background need to be clarified:
1. TypeScript is used for script level code in the engine.
2. [Babel](https://babeljs.io/) and [Rollup](https://rollupjs.org/) are used to compile TypeScript to JavaScript.
3. [ESLint](https://eslint.org/) is strongly recommended for all engine developers.
4. [VSCode](https://code.visualstudio.com/) is suggested for TypeScript coding.
5. In web runtime environments, the engine is fully running compiled TypeScript codes with some WebAssembly modules like physics engine.
6. In native runtime environments, the TypeScript codes are running based on the C++ codes and the JavaScript binding.
## Naming Rules
- Use camelCase naming convention for object and instance variables, properties, functions and namespaces.
```typescript
// bad
let FOOBar = {};
let foo_bar = {};
function FOOBar () {}
// good
let fooBar = {};
function fooBar () {}
```
- When using acronym for variables, properties or functions, keep all characters of the acronym case aligned. If the name starts with acronym then use lower case for all characters, otherwise capitalize all characters.
```typescript
// bad
let Id = 0;
let iD = 0;
function requireId () {}
// good
let id = 0;
let uuid = '';
function requireID () {}
class AssetUUID {}
```
- Use PascalCase naming convention for classes or modules
```javascript
// bad
let foobar = cc.Class({
foo: 'foo',
bar: 'bar',
});
let foobar = require('foo-bar');
// good
let FooBar = cc.Class({
foo: 'foo',
bar: 'bar',
});
let FooBar = require('foo-bar');
```
- Accessor API conventions
- Declare `public` property when the property is a direct value.
```typescript
// bad
class A {
get a ():number {
return this._a;
}
set a (val:number) {
this._a = val;
}
private _a: number;
}
// good
class A {
public a: number;
}
```
- Suggest to make the property private and provide `getXXX/setXXX` methods when data accessing requires heavy logic.
- Suggest to make the property private and provide `getXXX/setXXX` methods when data accessing implicitly affect other data.
```typescript
// not recommended
class A {
get property ():number {
// computeResult have some heavy logic
return this.computeResult();
}
}
// recommended
class A {
getProperty ():number {
// computeResult have some heavy logic
return this.computeResult();
}
}
// ---
// not recommended
class A {
get property ():number {
return this._prop;
}
set property (val: number) {
this._prop = val;
this._a = this.computeA();
}
private _prop: number;
private _a: number;
}
// recommended
class A {
getProperty ():number {
return this._prop;
}
setProperty (val: number) {
this._prop = val;
this._a = this.computeA();
}
private _prop: number;
private _a: number;
}
```
- Suggest to make the property private and provide public accessors if data accessing is light weight.
- In other conditions, please follow the existing API design in the file context.
- Use all capitalized characters with underscores as word separator for CONSTANTS.
```typescript
// bad
const PRIVATE_letIABLE = 'should not be unnecessarily uppercased within a file';
// bad
let THING_TO_BE_CHANGED = 'should obviously not be uppercased';
// bad
let REASSIGNABLE_letIABLE = 'do not use let with uppercase letiables';
// ---
// allowed but does not supply semantic value
export const apiKey = 'SOMEKEY';
// better in most cases
export const API_KEY = 'SOMEKEY';
// ---
// bad - unnecessarily uppercases key while adding no semantic value
export const MAPPING = {
KEY: 'value'
};
// good
export const Type = {
SIMPLE: 'value'
};
```
- Use underscore `_` as prefix for private properties.
```typescript
// bad
class A {
private __firstName__: string;
private firstName_: string;
}
// good
class A {
private _firstName: string;
}
```
- Use lowercase characters with dash `-` as word separator for TypeScript file names.
```bash
// bad
fooBar.ts
FooBar.ts
// good
foo-bar.ts
```
## Syntax references
- If a class property doesn't contain any initialization value, should consider using declare to avoid potential [issue](https://github.com/microsoft/TypeScript/issues/37640)
```typescript
// bad
class A {
public a:number;
constructor (a:number) {
// After compilation, the following line would be added to the constructor.
// this.a = void 0;
// As the type of `a` is changing, this could cause performance issue
this.a = a;
}
}
// good
class A {
public a:number = 0; // Ok.
constructor (a:number) {
// After compilation, the following line would be added to the constructor.
// this.a = 0;
// The type of `a` is constant
this.a = a;
}
}
// best
class A {
public declare a:number;
public b:undefined | object; // OK: b won't be reassigned in constructor
public declare c:object|null;
constructor (a:number, c:object) {
this.a = a;
this.c = c;
}
}
```
- Suggest to use `Object.create(null)` to create dictionaries, whose contents will be added or deleted frequently.
```javascript
// bad
let map = new Object();
// bad
let map = {};
// good
let map = Object.create(null);
```
- Use strict comparison `===` and `!==` instead of `==` and `!=`
## Other coding conventions
- Use 4 spaces indent.
```typescript
// bad
function () {
∙let name;
}
// bad
function () {
∙∙let name;
}
// very bad
function () {
∙∙<tab>let name;
}
// good
function () {
∙∙∙∙let name;
}
```
- Don't leave tailed spaces, and leave an empty line at the end of the file.
```typescript
// bad
function () {∙
∙∙∙∙let name;∙
}
/* EOF */
// good
function () {
∙∙∙∙let name;
}
/* EOF */
```
- Always add `;` at the end of a code line.
```typescript
// bad
proto.foo = function () {
}
// good
proto.foo = function () {
};
// bad
function foo () {
return 'test'
}
// very bad
// returns `undefined` instead of the value on the next line,
// always happens when `return` is on a line by itself because of Automatic Semicolon Insertion!
function foo () {
return
'test'
}
// good
function foo () {
return 'test';
}
// bad
function foo () {
};
// good: this is not a code line
function foo () {
}
```
- Suggest to keep `{` with the previous line.
```typescript
// bad
if ( isFoobar )
{
}
// good
if ( isFoobar ) {
}
// bad
function foobar ()
{
}
// good
function foobar () {
}
// bad
let obj =
{
foo: 'foo',
bar: 'bar',
}
// good
let obj = {
foo: 'foo',
bar: 'bar',
}
```
- Leave one space before `{`
```typescript
// bad
if (isJedi){
fight();
}
else{
escape();
}
// good
if (isJedi) {
fight();
}
else {
escape();
}
// bad
dog.set('attr',{
age: '1 year',
breed: 'Bernese Mountain Dog',
});
// good
dog.set('attr', {
age: '1 year',
breed: 'Bernese Mountain Dog',
});
```
- Leave one space after `if`, `else`, `while` and `switch`
```typescript
// bad
if(isJedi) {
fight ();
}
else{
escape();
}
// good
if (isJedi) {
fight();
}
else {
escape();
}
```
- Leave one space before and after binary and ternary operators.
```typescript
// bad
let x=y+5;
let left = rotated? y: x;
// good
let x = y + 5;
let left = rotated ? y : x;
// bad
for (let i=0; i< 10; i++) {
}
// good
for (let i = 0; i < 10; i++) {
}
```
- Some function declaration references
```typescript
// bad
let test = function () {
console.log('test');
};
// good
function test () {
console.log('test');
}
// bad
function test () { console.log('test'); };
// good
function test () {
console.log('test');
}
// bad
function divisibleFunction () {
return DEBUG ? 'foo' : 'bar';
}
// best
let divisibleFunction = DEBUG ?
function () {
return 'foo';
} :
function () {
return 'bar';
};
// bad
function test(){
}
// good
function test () {
}
// bad
let obj = {
foo: function () {
}
};
// good
let obj = {
foo () {
}
};
// bad
array.map(x=>x + 1);
array.map(x => {
return x + 1;
});
// good
array.map(x => x + 1);
```
- Suggest to leave empty line between code blocks.
```typescript
// bad
if (foo) {
return bar;
}
return baz;
// good
if (foo) {
return bar;
}
return baz;
// bad
const obj = {
x: 0,
y: 0,
foo () {
},
bar () {
},
};
return obj;
// good
const obj = {
x: 0,
y: 0,
foo () {
},
bar () {
},
};
return obj;
```
- Semicolon alignment.
```typescript
// bad
let story = [
once
, upon
, aTime
];
// good
let story = [
once,
upon,
aTime,
];
// bad
let hero = {
firstName: 'Ada'
, lastName: 'Lovelace'
, birthYear: 1815
, superPower: 'computers'
};
// good
let hero = {
firstName: 'Ada',
lastName: 'Lovelace',
birthYear: 1815,
superPower: 'computers',
};
```
- Single line comments
```typescript
//bad
// good
```
- Multiple line comments
```typescript
/*
* good
*/
```
- API documentation comments
```typescript
/**
* good
*/
```
- Except for API documentation, all comments must be written in English
```js
// bad
// 中文注释不利于非中文开发者阅读代码
// good
// Please write all in file comments in English
```
## Other references
- [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript#table-of-contents)