console_variable - ryzom/ryzomcore GitHub Wiki

NeL provides a variable management layer. This variable management is an extension of the command system explained earlier and comes in two flavors: basic and dynamic. All variables have a naming convention to match the NeL naming convention for public members such as: MyVariable, SomeValue or UsefulSetting.

A basic NeL variable is a way to expose a concrete primitive to the command system for real-time interaction with the user. The following snippet of code allows the user to modify a variable using the command system as explained in the previous section:

uint32 MyVariable
NLMISC_VARIABLE(uint32, MyVariable, "MyVariable represents important runtime mechanics.");

This simple tidbit of code would allow a user to change the value of MyVariable by simply calling the ICommand execution method with "MyVariable 3" or to retrieve the current value by simply calling it with "MyVariable." In essence any variable you create with this macro becomes a simple command that can be called to set or display the value. You can see here that the basic variable macro takes three parameters: variable type, variable name (which must match a concrete variable name as in the example,) and a brief description of the variable which will be accessible under the variables category of the command help system.

Dynamic variables provide you a little more flexibility in the process of getting and setting the value of the variable. One of the core goals of this is to provide you access to a variable which you do not have direct access to (such as a private member of a class.) With a dynamic variable you do not need a variable or class dedicated to the macro/command - you could use some other object within your simulation. If you use an existing class you must implement get and set methods which match the type that you will define in the NLMISC_DYNVARIABLE macro. One of the great advantages to this over the basic variable is that you as an implementor are allowed to define the getter and setter methods which allows you to perform some logic. You may want your setter method to check the limits of the value being passed or to clamp it to a reasonable value. Here's an example of a dynamic variable at work:

class CMyDynVar
{
	int m_SomePrivateVariable;
 public:
	int get() { return m_SomePrivateVariable; }
	void set(int val) { m_SomePrivateVariable=val; }
};

CMyDynVar myDynVar;

NLMISC_DYNVARIABLE(int,SomePrivVar,"Access the private variable inside of CMyDynVar")
{
	// check what type of command this is
	if(get)
		*pointer = myDynVar.get();
	else // !get is assumed to be set
		myDynVar.set(*pointer);
}

In the example above we created a class and then created an instance of it in the global scope. This could easily have been a class with static members or a singleton, we didn't have to create an instance at the global scope - it just has to be accessible in some way from the dynamic variable class/logic.

The NeL framework provides a variety of existing built-in variables for use. Below is a comprehensive list of the variables provided by the framework. In a later section specifically about the NeLNS system there will be even more built-in variables available for use that are specific to the various provided services.

When developing your game or application you should keep a table of available variables similar to this for a quick reference.

Source