Files
cocos4/cocos/core/settings.ts
T
Santy-Wang 7bc135e1c7 adjust initialization process (#11143)
* adjust init process

* fix bugs

* restructure

* tweak

* delete useless code

* fix ci

* support more platform and fix some bugs

* mark internal

* tweak

* add docs

* add docs and little adjustment

* fix bugs

* adjust decorator execute order

fix mesh error

* fix bugs

* revert some change

* revert auto-generated code

* revert auto-generated code
2022-07-03 21:16:09 +08:00

175 lines
6.5 KiB
TypeScript

/*
Copyright (c) 2022 Xiamen Yaji Software Co., Ltd.
http://www.cocos.com
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated engine source code (the "Software"), a limited,
worldwide, royalty-free, non-assignable, revocable and non-exclusive license
to use Cocos Creator solely to develop games on your target platforms. You shall
not use Cocos Creator software for developing other software or tools that's
used for developing games. You are not granted to publish, distribute,
sublicense, and/or sell copies of Cocos Creator.
The software or tools in this License Agreement are licensed, not sold.
Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
import { HTML5 } from 'internal:constants';
import { legacyCC } from './global-exports';
declare const fsUtils: any;
/**
* @zh
* Settings 中的默认分组,通常与模块一一对应。
*
* @en
* The default grouping in Settings, which usually corresponds to the module.
*/
enum Category {
PATH = 'path',
ENGINE = 'engine',
ASSETS = 'assets',
SCRIPTING = 'scripting',
PHYSICS = 'physics',
RENDERING = 'rendering',
LAUNCH = 'launch',
SCREEN = 'screen',
SPLASH_SCREEN = 'splashScreen',
ANIMATION = 'animation',
PROFILING = 'profiling',
PLUGINS = 'plugins',
}
/**
* @zh
* 配置模块用于获取 settings.json 配置文件中的配置信息,同时你可以覆盖一些配置从而影响引擎的启动和运行,可参考 [game.init] 的参数选项说明。你可以通过 [settings] 访问此模块单例。
* @en
* The Settings module is used to get the configuration information in the settings.json configuration file,
* and you can override some of the configuration to affect the launch and running of the engine, as described in the [game.init] parameter options.
* You can access this single instance of the module via [settings].
*/
export class Settings {
static Category = Category;
/**
* Initialization
* @internal
*/
init (path = '', overrides: Record<string, any> = {}): Promise<void> {
for (const categoryName in overrides) {
const category = overrides[categoryName];
if (category) {
for (const name in category) {
this.overrideSettings(categoryName, name, category[name]);
}
}
}
if (!path) return Promise.resolve();
return new Promise((resolve, reject) => {
if (!HTML5 && !path.startsWith('http')) {
const result = fsUtils.readJsonSync(path);
if (result instanceof Error) {
reject(result);
} else {
this._settings = result;
resolve();
}
} else {
const xhr = new XMLHttpRequest();
xhr.open('GET', path);
xhr.responseType = 'text';
xhr.onload = () => {
this._settings = JSON.parse(xhr.response);
resolve();
};
xhr.onerror = () => {
reject(new Error('request settings failed!'));
};
xhr.send(null);
}
});
}
/**
* @zh
* 覆盖一部分配置数据。
*
* @en
* Override some configuration info in Settings module.
*
* @param category @en The category you want to override. @zh 想要覆盖的分组。
* @param name @en The name of the configuration in the category you want to override. @zh 分组中想要覆盖的具体配置名称。
* @param value @en The value of the configuration you want to override. @zh 想要覆盖的具体值。
*
* @example
* ```ts
* console.log(settings.querySettings(Settings.Category.ASSETS, 'server')); // print https://www.cocos.com
* settings.overrideSettings(Settings.Category.ASSETS, 'server', 'http://www.test.com');
* console.log(settings.querySettings(Settings.Category.ASSETS, 'server')); // print http://www.test.com
* ```
*/
overrideSettings<T = any> (category: Category | string, name: string, value: T) {
if (!(category in this._override)) {
this._override[category] = {};
}
this._override[category][name] = value;
}
/**
* @zh
* 查询配置模块中具体分组中的具体配置值。
*
* @en
* Query specific configuration values in specific category in the settings module.
*
* @param category @en The name of category to query. @zh 想要查询的分组名称。
* @param name @en The name of configuration in category to query. @zh 分组中想要查询的具体的配置名称。
* @returns @en The value of configuration to query. @zh 想要查询的具体配置值。
*
* @example
* ```ts
* console.log(settings.querySettings(Settings.Category.ENGINE, 'debug')); // print false
* ```
*/
querySettings<T = any> (category: Category | string, name: string): T | null {
if (category in this._override) {
const categorySettings = this._override[category];
if (categorySettings && name in categorySettings) {
return categorySettings[name] as T;
}
}
if (category in this._settings) {
const categorySettings = this._settings[category];
if (categorySettings && name in categorySettings) {
return categorySettings[name] as T;
}
}
return null;
}
private _settings: Record<string, any> = {};
private _override: Record<string, any> = {};
}
export declare namespace Settings {
export type Category = typeof Category;
}
/**
* @zh
* Settings 模块单例,你能通过此单例访问 settings.json 中的配置数据。
* @en
* Settings module singleton, through this you can access the configuration data in settings.json.
*/
export const settings = new Settings();
legacyCC.settings = settings;