Clarify macro and settings

[SantyWang]

Motivation

• Clarify a principle about which macros need to be provided and whether they are opened in editor
• Clarify the difference between macros and settings
• Find a clear way to handle settings

Macro

All options determined at compiling time. Considering which macros need to be provided to developers, the following dimensions need to be considered。

Functionality Control

Ideally, all optional modules need to be provided with macros to control whether they are on or off
For example. The spine module is optional, and a marco should be provided to control whether it's on or off.

#ifdef CC_USE_SPINE
#include "cocos/spine.h"
#endif 

or when a module(such as Physics Module) has multiple implement backend. A macro should be provided to control which backend should be used.

#ifdef CC_USE_PHYSX
#include "physics/physx/PhysX.h"
#endif

Performance impacted

When a part of the function code has a performance impact, we need to define a macro to control whether it is on or off。

#ifdef CC_USE_MULTITHREAD
#include "threading/thread.h"
#endif

#ifdef CC_PROFILING
#include “profile.h”
#endif

Granularity and learning costs

When there are features that have little impact for most developers, but do make some difference for a very small percentage of developers, we retain the ability to control the macro, but in order not to increase the learning cost for most developers, the macro will not be displayed in the editor. Developers who need to control can do so by customizing the compiling configuration file.

const std:: string& AssetManager::getNativeUrl () {
#ifdef CC_USE_MD5
  return _nativeUrlWithMd5Ext;
#else
  return _nativeUrl;
#endif
}

Settings

All options can be changed in runtime or maybe take effect after restarting the game

Read/Write Configuration

The corresponding module needs to provide the settings that can be read or write by user and needs to handle the logic of changing the options.
For example.

class View {
   getDesignResolution () {
         return new Size(this._width, this._height);
   }

   setDesignResolution(width: number, height: number) {
       this._width = width;
       this._height = height;
   }
}

ReadOnly Configuration

This option cannot be changed dynamically during game playing, but can be changed by passing additional parameters in the command line tool or by modifying the configuration file to take effect the next time the game is restarted.
The corresponding module only provide the readonly interface. for example.

class GFXDevice {
   get isAntiAlias () {
      return this._isAntiAlias;
   }
}

Introduce BuildSettings Module

• Read the configuration file(settings.json for now) at Engine initialization time，and initialize all settings.
• Provide readonly interface for all settings.

class BuildSettings {
    // initialize
    initialize () {
        const json = readFile('settings.json');
        this._isAntiAlias = json.isAntiAlias;
        this._designResolution = new Size(json.designResolutionWidth, json.designResolutionHeight);
        
    }
    get designResolution () {
        return this._designResolution;
    }

    get isAntiAlias () {
        return this._isAntiAlias;
    }
}

class ComponentTest extends Component {
   start () {
       // true
       const antiAlias = BuildSettings.instance.antiAlias;
   }
}

• All other module use this module to initalize all options's default value and dont care how the real configuration file work

class View {
   initialize () {
        this._width = BuildSettings.instance.designResolution.width;
        this._height = BuildSettings.instance.designResolution.height;
   }

   getDesignResolution () {
         return new Size(this._width, this._height);
   }

   setDesignResolution(width: number, height: number) {
       this._width = width;
       this._height = height;
   }
}

class GFXDevice {
   initialize () {
       // initialize readonly option default value. 
       this._isAntiAlias = BuildSettings.instance.isAntiAlias;
   }
   get isAntiAlias () {
      return this._isAntiAlias;
   }
}

class ComponentTest extends Component {
   void start () {
      // set read/write options
      view.setDesignResolution(BuildSettings.instance.designResolution.width, BuildSettings.instance.designResolution.height);
   }
}

class BuiltinResMgr {
   void init () {
      // initialize 
      loadBuiltinAsset(BuildSettings.instance.buildinAsset);
   }
}

• All options in BuildSettings can not be changed

class ComponentTest extends Component {
   update () {
      // error! can not change readonly option
      gfxDevice.isAntiAlias = false;
      // ok! set read/write options, take effect directly
      view.setDesignResolution(math.random(), math.random());
      // error! can not change buildSettings in game playing;
      BuildSettings.instance.designResolution = new Vec2(960, 640);
   }
}

Introduce UserData(or other better name?) Module

Provide a module to help developer to save some information for current game state, and can be load any time.

class UserData {
     addItem (key: string，val: bool | string | number): void;
     getItem (key: string): bool | string | number;
}

To do list

• clear all marcos and settings in engine
• refactor cc.macro and move options to corresponse module
• introduce BuildSettings module to handle settings file
• rename LocalStorage to UserData?
• All module use BuildSettings to initialize

[minggo]

clear all macros and settings in engine

What does it mean? Could you please describe it in more detail?

[SantyWang]

I mean we need to confirm the macros currently used in the engine, there is no violation of the above principles.

[minggo]

Got it.

[dumganhar]

So the configuration file(settings.json for now) could be modified by BuildSettings API and Editor configuration?
BuildSettings could override the setting in editor?
BuildSettings is settings set in build time and I think the name is not suitable.
Why do developers need BuildSettings API ? Why not just use editor to control setting informations?

[SantyWang]

Yeah, editor can change build settings. but some settings (such as resolution) can be customize by developer in runtime according to player's environmentation

[jareguo]

For non-building period settings, I think we should also distinguish clearly what is a config and what is a API.

1. config

Affect engine initialization and are not something that can be determined at build time, and is now often hard coded in main.js. For example, environment information (SUPPORT_TEXTURE_FORMATS), resource information (paths、data version), various APP IDs.

2. API

Any setting that can be dynamically modified should exist as an API (of corresponding module).
It's not necessary to be placed in some global XxxSettings or XxxPerfs.

For example:

• cc.BuildSettings.designResolution -> cc.View.designResolution
• cc.BuildSettings.TOUCH_TIMEOUT -> cc.Input.TOUCH_TIMEOUT
• cc.BuildSettings.ENABLE_WEBGL_ANTIALIAS -> cc.Game.ENABLE_WEBGL_ANTIALIAS

[SantyWang]

Any setting that can be dynamically modified should exist as an API (of corresponding module).
It's not necessary to be placed in some global XxxSettings or XxxPerfs.

Sure, I totally agreed, that's why buildSettings's interfaces are all readonly. This BuildSettings is just some preset default values, the user should not bother to make any changes. If you are concerned about coupling BuildSettings with the code of a specific module, can also provide an API in the form of a query key instead.

class BuildSettings {
    // initialize
    initialize () {
        this.json = readFile('settings.json');
    }
    querySettings(key: string): bool | string | number;
}