AZ::Console
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE |
The AZ::Console
class provides a set of macros for defining variables and
mapping functions that you can use to interact with in-game variables and processes. Use the
macros defined in this class to set the console variables (cvars) and functors (cfuncs) for your
game, and then access them through the Lumberyard console.
AZ::Console
is defined in the following header:
%INSTALL-ROOT%\dev\Code\Framework\AzCore\AzCore\Console\IConsole.h
The console found inside AzCore
is a console and cvar system intended
to replace the legacy CryEngine console and cvar system. This system is free of any CryEngine
code, and depends only on AzCore
.
AZ::Console
features:
-
Stubbed support for multiplayer (as of v1.24). Lumberyard will eventually enable cvar replication across multiplayer instances using GridMate.
-
Basic access protections and anti-cheat mechanisms for locking down cvars and cfuncs in release builds.
-
Default support for several C++ types, including bool (Boolean), stdint (all types), floats, doubles, vectors and quaternions, and enums (enumerations).
-
Flexible and expandable type support. You can add support for new cvar types without altering the console code directly.
-
Support for the legacy CryEngine console, specifically to reduce user confusion. For users of the in-game console, legacy cvars and
AZ_CVAR
cvars appear identical.

As of Amazon Lumberyard version 1.24, AZ::Console does not support the following features present in the CryEngine console:
-
Registration of cvars at runtime by name. Formerly, you could register a CryEngine cvar using
IConsole->Register<String/Int/Float>()
and then retrieve the value of that cvar withIConsole->GetCVar()
.AZ::Console
cvars must be declared at compile-time using one of the macros in IConsole.h. -
Custom cvar/cfunc autocomplete callbacks. Formerly, you could specify an autocomplete callback and attach it to a CryEngine cvar.
AZ::Console
currently does not support this functionality. -
Remote console support. The CryEngine console allows remote access by opening a socket on a provided port, and then listening for console commands issued to that socket.
AZ::Console
currently does not support this functionality.
Topics
Console variables (cvars)
Declare a cvar using one of two macros from IConsole.h:
AZ_CVAR(_TYPE, _NAME, _INIT, _CALLBACK, _FLAGS, _DESC) //Standard cvar macro, provides no external linkage.
AZ_CVAR_EXTERNABLE(_TYPE, _NAME, _INIT, _CALLBACK, _FLAGS, _DESC) //Cvar macro that creates a console variable with external linkage.
Parameters:
-
_TYPE: The base type of the cvar.
-
_NAME: The name of the cvar.
-
_INIT: The initial value to assign to the cvar.
-
_CALLBACK: An optional callback function invoked when a cvar changes value. Note: These macros do not guarantee that this callback will be run on a specific thread. The implementor of the callback handler is responsible for ensuring thread safety.
-
_FLAGS: One or more
AZ::Console::FunctorFlags
that are used to mutate behavior. Use the logical AND (&&
) and OR (||
) operators to combine flags. If you do not have any flags to set, useFunctorFlags::None
. -
_DESC: String that provides a short description of the cvar for display.
To declare a new cvar in your code, include the IConsole.h
header.
Then use one of the cvar macros (such as AZ_CVAR
) to declare your new
console variable in your own code (.cpp) files.
AZ_CVAR and AZ_CVAR_EXTERNABLE variables can be declared only in C++ code (.cpp) files. AZ_CVAR_EXTERNED variables, however, can be declared in either C++ code (.cpp) or header (.h) files.
Here are some examples.
AZ_CVAR(int32_t, cl_GameServiceRefreshTimeMs, 1000, nullptr, FunctorFlags::None, "Controls the auto-refresh delay for all gameService data, time in milliseconds"); AZ_CVAR(bool, cl_QuitOnHubDisconnect, false, nullptr, FunctorFlags::None, "If enabled, the client executable will terminate on disconnect");
void OnConsoleResUpdate(const int32_t& a_NewWidth) { // Run update for new value } AZ_CVAR(int32_t, sv_ConsoleWidth, 160, OnConsoleResUpdate, FunctorFlags::ReadOnly, "The width of the server console window");
AZ_CVAR_EXTERNABLE(uint16_t, net_ServerRateMs, 33, nullptr, FunctorFlags::ReadOnly, "Server tick rate to use for network relevent simulations");
Optionally, use the following name prefixes to help organize groups of cvars:
-
sv_: For server only cvars
-
cl_: For client only cvars
-
bg_ : "Both games" for common cvars (client and server)
These prefixes are useful to quickly limit the scope of autocomplete, and to see groups of associated cvars in the console. You can use your own prefixes as well.
To make an existing console variable external (extern), use the
AZ_CVAR_EXTERNED
macro:
AZ_CVAR_EXTERNED(_TYPE, _NAME)
Make sure that the _TYPE and _NAME parameters match those of the previously defined cvar.
Console functors (cfuncs)
Console functions allow you to register a command with the console that's not associated with a specific type or value. In Lumberyard, they're purely a mechanism to allow a method to be invoked directly from the Lumberyard in-game console.
There are two types of cfuncs: one to invoke class member methods
(AZ_CONSOLEFUNC
), and one to invoke static methods
(AZ_CONSOLEFREEFUNC
).
To declare a class member method cfunc, use the AZ_CFUNC
macro from
IConsole.h
:
AZ_CONSOLEFUNC(_CLASS, _FUNCTION, _INSTANCE, _FLAGS, _DESC)
Parameters:
-
_CLASS: The class that contains the method (function) for invocation.
-
_FUNCTION: The method to invoke as a callback. Note: These macros do not guarantee that this callback will be run on a specific thread. The implementor of the callback handler is responsible for ensuring thread safety.
-
_INSTANCE: The instance of the class on which this method gets invoked (usually set to
this
for the current instance). -
_FLAGS: One or more
AZ::Console::FunctorFlags
that are used to mutate behavior. Use the logical AND (&&
) and OR (||
) operators to combine flags. If you do not have any flags to set, useFunctorFlags::None
. -
_DESC: String that provides a short description of the cfunc for display.
Some examples of cfunc declarations:
class Example { public: Example() { AZ_CONSOLEFUNC(Example, Method, this, FunctorFlags::DontReplicate, "Executes the Method method on this Example instance, invoke in the console using Example.Method"); } void Method(const StringSet&) {} };
To declare a cfunc for a static method (or other non-member function), use the
AZ_CONSOLEFREEFUNC
macro:
AZ_CONSOLEFREEFUNC(_FUNCTION, _FLAGS, _DESC)
Parameters:
-
_FUNCTION: The static method to invoke as a callback. Note: These macros do not guarantee that this callback will be run on a specific thread. The implementor of the callback handler is responsible for ensuring thread safety.
-
_FLAGS: One or more
AZ::Console::FunctorFlags
that are used to mutate behavior. Use the logical AND (&&
) and OR (||
) operators to combine flags. If you do not have any flags to set, useFunctorFlags::None
. -
_DESC: String that provides a short description of the cfunc for display.
Example:
void ForceEnableMetrics(const StringSet&) {} AZ_CONSOLEFREEFREEFUNC(ForceEnableMetrics, FunctorFlags::Null, "If called, force enable metrics");
Optional flags
AZ::Console
provides a set of flags that can be passed to cvar and cfunc
declarations and indicate how they should be handled:
enum class FunctorFlags { Null = 0 // Empty flags , DontReplicate = (1 << 0) // Should not be replicated (CURRENTLY UNUSED) , ServerOnly = (1 << 1) // Should never replicate to clients (CURRENTLY UNUSED) , ReadOnly = (1 << 2) // Should not be invoked at runtime , IsCheat = (1 << 4) // Should not be shown in the console for autocomplete , IsDeprecated = (1 << 5) // Command is deprecated, show a warning when invoked , NeedsReload = (1 << 6) // Level should be reloaded after executing this command , AllowClientSet = (1 << 7) // Allow clients to modify this cvar even in release (this alters the cvar for all connected servers and clients, be VERY careful enabling this flag) (CURRENTLY UNUSED) };
Adding support for new console variable types
To add support for a new cvar type, override the two template methods that convert the custom type to a space-delimited string from a vector of space-delimited string inputs.
As an example, an override that converts AZ::Vector3
to a string and back to
a value is declared like this:
namespace AZ { // CVar compatibility namespace ConsoleTypeHelpers { template <> AZStd::string ValueToString<AZ::Vector3>(const AZ::Vector3& a_Value); template <> bool StringSetToValue<AZ::Vector3>(AZ::Vector3& a_OutValue, const StringSet& a_Arguments); } }