Programming

Programming

Languages

Transfering from Unity to Lumberyard can be overwhelming because CryEngine, the base engine of Lumberyard, is AAA industry veteran used in game development, where Unity has been built-up from the indie perspective and evolved into a AAA engine. Where in Unity, programmers are only given the option of using the language C#, Lumberyard offers the Lua and C++ language as well as script editor, Lumberyard’s visual programming.

In the current version of Lumberyard, it is much more difficult to start programing coming from Unity where function documentation is abundant and any question you may have has probably been answered in a few forums and by the Unity developers through updates to the engine. Lumberyard is currently lacking much of this, which leaves it to the developer to educate one another, be technically competent in reading the lines of documentation, and be able to read engine code. Unlike Unity where engine code is hidden, quite literally by a paywall, the Lumberyard source code is openly available to read to understand functionality as well as modify to meet your needs. Having access to the engine allows you to create missing functionality, where in Unity most functionality required is there, the current Lumberyard version is missing/removing some basic functionality which is useful in game development. Simple functionality that Unity developer’s take for granted, such as FindObjectByType, isn’t built into Lumberyard and similar functionality is currently being deprecated and rendered unusable.

Lumberyard’s Lua scripting is analogous to Unity’s C# in that it is the built-in, default programming language. Lumberyard includes a Lua editor, similar to Monodevelop, however with documentation of classes, bus, and notification systems built-in. This documentation however, doesn’t mean there is autocomplete feature, it requires you to understand how the Lua language operates more than C# in Unity does. We recommend you start development using Lua, and once you’ve become comfortable with Lua delve into the C++ code as the logic is coupled with the engine logic.

When assigning source code to an entity, for a Lua script you must take an additional step of assigning a Lua Script component and then assigning the script as a value to the script variable of that component. A C++ component acts the same in assigning as a C# script.

Legacy Versions

Unlike with Unity documentation where you can trust a source from over a year ago, Lumberyard is advancing and evolving so rapidly that it is dangerous to rely on anything prior to the release of your current build. Even documentation after your current build was released can be of questionable authority, because the Amazon team is struggling to keep up with their own progress. What we recommend is to try things that worked in the past, and adapt based on the version. Adapting may be you looking into engine code or simply trial and error, once you have a successful compile make sure you let your fellow developers know. Lumberyard will only become as big as Unity if the developers help build a community that welcomes newcomers and provides answers for one another. [expand]

Code Editor

Although Monodevelop is packaged with Unity and set at the default external editor tool for editing scripts, it isn’t the same as the Lua Editor. Monodevelop and Visual Studio are independent development environment, they can be used to develop other software outside of Unity. The Lua Editor is exclusively for the Lumberyard engine, and isn’t as useful for other application, although it may be used as an overqualified text editor. Another editor can be used to edit your script, however it won’t be integrated into the engine, there currently isn’t a way to set an external preference for editor like in Unity. Which means, whenever a script is double-clicked in Lumberyard the Lua Editor will open rather than the preferred editor.

Scripting

Outlined are pieces of a Lumberyard Lua script compared with Unity, see the technical documentation for structure. Adjusting to the language change will take time, especially with Lua being focused more on non-programmers ease to use rather than a programmer focus, with arrays starting a 1 and the language itself not being object oriented. Calling functions uses a colon (:) rather than a dot, variables aren’t typed and variables can be added to the table (“class”) in any function.

Requiring a script in Lumberyard is akin to having the using namespace. The parameter required holds what was returned from the require script, so to access variables index into the table (require.variable) and to call functions has the same syntax (require:method). Any global variables/functions from the required script will also be included.

local required = require("scripts.path.to.file");

The table, typically the first defined, returned at the end of the script will be the script/functionality exposed to the inspector. If the script isn’t returned the editor won’t recognize the script as a valid script.

local ScriptName =
{
}
return ScriptName;

The properties table within the returned table are the variables exposed to the editor. The variables are similar to [SerializeField] variables from Unity, since the variables can’t be accessed from other scripts only the inspector.
Properties =
{
},


OnActivate within Lumberyard is like Start within Unity, since it will only be called once, once the entity is spawned within the level. Here the EBuses which will be required through the life of the script should be connected and stored.

function ScriptName:OnActivate()
end


OnDeactivate is correlated with OnDestroy, and is called when an entity is removed from the level or when the game exits play mode. Here the EBuses which are connected should be disconnected, if a EBus is disconnected it can run while in edit mode, like [ExecuteInEditMode] but typically not intended.

function ScriptName:OnDeactivate()
end


OnTick is Lumberyard’s frame update function, Unity’s Update. Unlike in Unity where delta time can be retrieved from any function of the script, Lumberyard passes the delta time only to the OnTick function (which can then be stored to be used elsewhere). OnTick isn’t connected initially, even if the function is present, it requires the tick bus to be connected in another function to be used.

function ScriptName:OnTick(deltaTime, scriptPointTime)
end

Communicating with Scripts/GameOjbects

In Unity a GameObject can be gotten through different methods, such as FindObjectOfType<>, however in Lumberyard Event Buses are used. Event buses can only be created through C++ code, which requires compiling the game after each change, see live-editing. Finding specific entities in Lumberyard is difficult without learning how to properly use the event buses, and isn’t as trivial as it is in Unity. Lumberyard event buses do allow broadcasting information, sending to all listening entities, similar to Unity’s FindObjectsOfType<> however neither of these are typically good practice to use.

Once a Lua script has a reference to an entity, it cannot alter parameters or call functions of that script like Unity because as mentioned above the script itself isn’t known. There is no GetComponent<> built into the Lua scripting system, this behavior must also be programmed through event buses and isn’t a feature of Lua scripting. To generally communicate between entities in Lumberyard the gameplay bus is used.

Serialization/Reflection

Serialization/reflection is an important part of any game engine. From a higher level perspective of game engines, this is how variables, functions, etc are exposed to the users/designers. In Unity the “SerializeField” is used to expose variables to the inspector, in Lumberyard Lua scripting all variables in Properties table of the Lua script are exposed to the inspector. However, where in Unity the variables exposed in the inspector are defined in the order of declaration of the script, Lumberyard reorganizes the variables in alphabetical order (this is why sub-tables are useful). Lumberyard also has serialization/reflection of C++ classes/structs, which remain in order of declaration.

 

Live-Editing

Unity allows for live editing of parameters in the inspector during play, however Lumberyard restricts the mouse to the perspective viewport while in the Lumberyard software. The mouse cannot access the inspector, thus values cannot be changed while the game is playing like in Unity.

Where in Unity modifying a script requires the game to be stopped, modifying C++ code in Lumberyard requires the game to recompiled. What this means is the editor needs to be closed and a number of console commands need to be run to recompile the code (which can take minutes to complete). Only after the code is recompiled can the editor be reopened.