# cococs-creator-frame-3d

**Repository Path**: lehung/cococs-creator-frame-3d

## Basic Information

- **Project Name**: cococs-creator-frame-3d
- **Description**: Applicable to CocosCreator3.6 and above
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 73
- **Created**: 2023-07-25
- **Last Updated**: 2023-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# introduce
> At the beginning of the framework design, H5 and small game environments were mainly considered. The ultimate goal is to:<br/>
> 1. Better multi-person collaborative development experience. <br/>
> 2. Unify development specifications as much as possible (try to avoid verbal constraints). <br/>
> 3. Smaller first screen/first package size. <br/>
> 4. Smaller incremental update volume. <br/>
> 5. The ability to reuse common modules. <br/>

⚠️: After clicking on most framework directories, some description text will be generated on the property inspector page, which can be viewed. <br/>
⚠️: The framework temporarily does not allow customizing folders under assets. All folders can be created through the menu bar App. <br/>
⚠️: It is recommended to install the Code Spell Checker plug-in when using vscode. <br/>

# use
## 0. Initialization project
* Execute ```npx @gamex/cc-cli@latest``` or ```npx --registry=https://registry.npmjs.org @gamex/cc-cli@latest`` in an empty folder `
## 1. Update project framework
* Execute ```npm run upgrade``` in the project root directory
## 2. Use built-in package
* Execute ```npm run package``` in the project root directory

# key point
## 0. ESLint
* Install the ESLint plug-in in vscode
* Execute **npm install** in the project root directory

## 1. UI
* Create UI through the menu bar App/Create/View, and it will be automatically created under assets/app-bundle/app-view.
* The UI is divided into 4 categories: Page, Paper, Pop and Top. They all inherit from BaseView, and their levels increase in order (same as under camera), that is: Top > Pop > Paper > Page.
* If you select destroy in UI's HideEvent, statically referenced resources will be automatically cleaned up.
* The landing page is composed of Page and Paper. Through this model, multi-person collaborative development can be easily realized.
* Page and Paper distinguish between 3D and 2D when created. They will be set as child nodes of scene/Root3D/UserInterface and scene/Root2D/UserInterface respectively when instantiated.
```
// Open a UI (if the automatic prompt does not appear, please open the executor.ts file in vscode)
app.manager.ui.show<UI class>({
     name: 'Automatically prompt UI name',
     data: Automatically prompt the parameters required by the onShow method of the UI class,
     onShow:(){},
     onHide:(result){ //Automatically prompt the return value type of onHide of the UI class },
     onError:(){}
});
app.manager.ui.hide({
     name: 'Automatically prompt UI name',
     data: Automatically prompt the parameters required by the onHide method of the UI class,
     onHide:(result){ //Automatically prompt the return value type of onHide of the UI class }
})
// Display general loading (automatically called when loading UI)
app.manager.ui.showLoading();
// Hide universal loading
app.manager.ui.hideLoading();
// Add touch shielding
const uuid = app.manager.ui.addTouchMask();
//Remove touch blocking
app.manager.ui.removeTouchMask(uuid: string);
...//etc
```
## 2. Audio
Generate a directory through the menu bar App/Create/Sound. The location is under the assets/app-bundle/app-sound directory. It is divided into two types: effect and music.
```
app.manager.sound.playMusic({
     name: 'Auto prompt'
})
app.manager.sound.playEffect({
     name: 'Auto prompt'
})
//For other apis and parameters, you can view the relevant interfaces
```

## 3. Global timer
```
// What it returns is a Component, and you can use its schedule or scheduleOnce methods.
app.manager.timer.get('My custom timer name')
```

## 4. Global events
```
app.manager.event.on
app.manager.event.once
app.manager.event.off
app.manager.event.targetOff
```

## 5. Global loader
* Some simple encapsulation of cc.assetManager
```
app.manager.loader.load
app.manager.loader.loadDir
app.manager.loader.preload
```

## 6. Global library
```
//Task: The ability to perform simultaneous execution, sequential execution, combined execution, retry, etc. is more useful than Promise
app.lib.task
// Local storage: permanent storage, daily storage, weekly storage
app.lib.storage
```

## 7. Custom Manager
* Create a custom Manager through the menu bar App/Create/Manager, located under assets/app-builtin/app-manager
```
app.manager.xxx
```

## 8. Customized Control
* Create a custom Control through the menu bar App/Create/Control, located under assets/app-builtin/app-control
* The difference between it and Manager is: Manager prefers the functions of some global classes, while Control prefers to be the external interface of a certain UI (the UI cannot be accessed directly)
```
   1. As external output, new variables and methods can be created inside Control, and externally (called through XXXControl.inst) variables and methods will automatically become read-only.
   2. There is an additional emit and call method inside Control for emitting events. This method is inaccessible anywhere else. The difference is that the call method will only execute the first registered event and get the return value.
   Each View can bind a Control by inheriting BaseView.BindControl(Control).
   After binding, this Control instance can be accessed through this.control inside the View script. Unlike the inst call, it is unrestricted (properties, etc. are not read-only).
   And you can receive and close events that receive emit or call in Control through on, once, and off in this.control.
```

## 9. Custom Model
* Create a custom Model through the menu bar App/Create/Model, located under assets/app-builtin/app-model
```
app.data.xxx
app.config.xxx
```

## 10. Use expansion package (package)
You can use some extension packages based on npm management
* Use built-in expansion packs
```
//Execute in the project root directory
npm run package

// Use in project
import {} from 'db://pkg/@gamex/xxx'
```
* You can also upload some packages yourself and then use the following command to manage them
```
// Execute addition in the project root directory
npm run pkg:add @xxx/test
// Execute removal in the project root directory
npm run pkg:remove @xxx/test
//Perform updates in the project root directory
npm run pkg:update

// Use in project
import {} from 'db://pkg/@xxx/test'
```
If the above addition or deletion operation results in `editor error` or `runtime code` not updated, try clicking the `refresh button` in the upper right corner of the resource manager, or `menu [Developer->Cache->Clear] Code cache]`, the error problem can be solved (BUG of CocosCreator resource manager).

## 11. Others
* assets/app-appinit is the first screen page of the game, which can render loading content and initialize some things needed by the business.
* assets/app/handle.ts is the framework’s built-in life cycle function. There are some life cycle events under App.EventType, which can be monitored through app.on or app.once
* assets/app/setting.ts are some initial configurations for the framework, for example:
```
// You can set the background color, transparency and other information of the pop-up window globally (you can also override the onShade method in a certain UI to customize the background color and other information of a certain UI)
UIManager.setting.shade = {...}
```