• # Shift Quantum Systems

General and Gameplay Programming

In this article, we will cover a few aspects of the systems implemented in the code base of Shift Quantum. From how blocks composing the levels are managed, to our command system for the in-game level editor, including how we generate those commands from the HUD, you will have a better idea of how we handle all of this in code.

# Separation between model and the view

Because basically our levels are a grid of blocks, early on in the development of the game we thought it would be best to separate the data from its representation. This would have several advantages:
• The game would only have to manipulate some raw and abstract data without having to take care of where to place the blocks for example.
• It's possible to have multiple representations of the model: a 3D representation like now, but also a complete 2D sprite based view if needed ( to generate a map for big levels for example ).
• It is very easy to write unit tests to validate that the data is correctly handled by the model, enforcing the validity of the various operations on the model throughout the development.
• The model contains all the information related to the level, like the width and height, the current color space (Black or White), the rotation of the grid, or all the blocks coordinates. It also contains information used only by the in-game level editor, like the cursor coordinates and rotation.
The model communicates with the other classes using events. Lots of events... Here is a non exhaustive list of the names of the events to give you a rough idea: FOnInitializedEvent, FOnWorldRotationStartedEvent, FOnWorldRotationEndedEvent, FOnWorldColorUpdatedEvent, FOnBlockRegisteredEvent,FOnBlockUnRegisteredEvent, FOnDimensionsUpdatedEvent, etc?EUR? The other classes which want to know when something happens in the model just need to subscribe to those events and react accordingly. For example, the level view is interested for example in knowing when the dimensions of the grid are updated, to adjust the boundaries around the play space, or when a block is registered, so the view can move the block to its correct location in the 3D world (because the model does not even know the blocks are in a 3d space), and so on?EUR? One thing to note is that the model does not perform any logic when you update its data. It?EUR(TM)s up to the caller to take care of removing an existing block before adding a new one at the same coordinates. More about that later in the commands section.

# Level Editor Commands

During the incubation meetings, maybe the first answer given to the question "What do you think is important to have in an in-game editor?" was an Undo-Redo system for all the operations available. So we obviously had to implement a command pattern. This is a very well-know pattern, so I don't think we need to dive a lot in the details. But if you need a refresher, here are some links. Nonetheless, I can give you one advice: your command classes must be as lightweight as possible. No logic should happen in the commands, because the more logic you put inside, the more complicated it will be for you to handle the Undo and Redo parts of the contract. As such, the declaration of the base command class is very simple and straightforward:  UCLASS() class SHIFTQUANTUM_API USQCommand : public UObject { GENERATED_BODY() public: USQCommand(); FORCEINLINE const FSQCommandContext & GetContext() const; virtual void Finalize(); virtual bool Do(); virtual void UnDo(); void Initialize( const FSQCoords & coords ); protected: UPROPERTY( VisibleAnywhere ) FSQCommandContext Context; }; I think you will agree it can hardly be less than that. You may notice we don't have a ReDo function, because Do will be used in both scenarios. To execute those commands (and of course to UnDo and Redo them), we have a command manager component attached to our level editor actor. As you can guess, its definition is very simple: class SHIFTQUANTUM_API USQCommandManagerComponent : public UActorComponent { GENERATED_BODY() public: USQCommandManagerComponent(); bool ExecuteCommand( USQCommand * command ); bool UnDoLastCommand( FSQCommandContext & command_context ); bool ReDoLastCommand( FSQCommandContext & command_context ); void ClearCommands(); private: UPROPERTY( VisibleAnywhere, BlueprintReadonly ) bool bCanUndo; UPROPERTY( VisibleAnywhere, BlueprintReadonly ) bool bCanRedo; UPROPERTY( VisibleAnywhere ) TArray< USQCommand * > DoneCommands; UPROPERTY( VisibleAnywhere ) TArray< USQCommand * > UnDoneCommands; };  And its implementation is a classic too. For example, the ExecuteCommand:  bool USQCommandManagerComponent::ExecuteCommand( USQCommand * command ) { if ( command == nullptr ) { UE_LOG( LogSQ_Command, Error, TEXT( "Can not execute the command because it is null." ) ); return false; } if ( command->Do() ) { DoneCommands.Add( command ); for ( auto undone_command : UnDoneCommands ) { undone_command->Finalize(); } UnDoneCommands.Empty(); bCanUndo = true; bCanRedo = false; return true; } return false; }  One function which deserves a bit of explanation is Finalize. You can see this function is called on commands which have been UnDone at the moment we execute a new command, before we empty the UnDoneCommands array. This allows up to do some cleanup because we know for sure the commands won?EUR(TM)t be executed again. For example, when we want to add a new block in the world, the command generator will spawn that block, initialize it, and pass the block as a pointer to the RegisterBlock command. When we Do that RegisterBlock command, we just kind of toggle on the block (make it visible, set up the collisions, etc?EUR?), and when we UnDo the command, we do the opposite (hide it, disable the collisions, and so on?EUR?). Finalize then becomes the function of choice to destroy the actor spawned by the command generator.  void USQCommandRegisterBlock::Finalize() { if ( ensure( Block != nullptr ) ) { GetOuter()->GetWorld()->DestroyActor( Block ); } } bool USQCommandRegisterBlock::Do() { Super::Do(); return ensure( GetTileManagerComponent()->RegisterBlock( *Block, Context.Coords ) ); } void USQCommandRegisterBlock::UnDo() { Super::UnDo(); ensure( GetTileManagerComponent()->UnregisterBlock( Context.Coords ) ); } void USQCommandRegisterBlock::Initialize( const FSQCoords & coords, ASQBlock & block ) { Super::Initialize( coords ); Block = █ }  There are two things worth noting:
1. Because the command manager only executes one command at a time, and because any action we do is made of several commands (for example, adding a block in the grid is made of at least 2 commands : remove the existing block at the cursor coordinates, then register the new block), we have a special command class named USQCommandComposite. It stores an array of sub-commands. Those sub-commands are executed linearly in Do and in reverse order in Undo.
2. You may have noticed the FSQCommandContext structure. Each command holds a context internally, which is used to store some global informations at the moment the command is initialized (just before being executed for the very first time). This allows us to restore the cursor position and the zoom level of the camera when we undo / redo any command, allowing the player to have the editor in the same state as it was when he first executed an action.

# Command generation

Because our commands are very simple, we need to put the logic elsewhere. And because we need a way to bind the generation of those commands to the UI, we created class hierarchy deriving from UDataAsset. This allows us to make properties editable in the UE4 editor such as the sprite to display in the HUD, the text to display under the sprite, the static mesh to assign to the cursor, or the maximum number of instances of a given actor which can be spawned in the level (for example, we only allow one start point and one exit door). Here is an excerpt of the definition of this class:  UCLASS( BlueprintType, Abstract ) class SHIFTQUANTUM_API USQCommandDataAsset : public UDataAsset { GENERATED_BODY() public: USQCommandDataAsset(); FORCEINLINE bool CanBeExecuted() const; virtual USQCommand * CreateCommand( ASQLevelEditor & level_editor ) const PURE_VIRTUAL( USQCommandDataAsset::CreateCommand, return nullptr; ); protected: UPROPERTY( BlueprintReadonly ) uint8 bCanBeExecuted : 1; UPROPERTY( EditAnywhere ) TSubclassOf< ASQBasicBlock > BasicBlockClass; UPROPERTY( EditAnywhere, BlueprintReadonly ) UTexture2D * UITexture; UPROPERTY( EditAnywhere, BlueprintReadonly ) FText DisplayText; // … };  For example, here is the editor view of a command data asset used to add a game block in the level: Our command generator assets are grouped by categories, which is another UDataAsset derived class: In the in-game editor UI widget, we just iterate over all the commands of the selected category, and add new buttons in the bottom bar: When the player presses the A button of the gamepad, we know the selected command data asset. Now, we just need to create the command out of this data asset, and give it to the command manager command:  bool ASQLevelEditor::ExecuteCommand( USQCommandDataAsset * command_data_asset ) { if ( command_data_asset == nullptr ) { return false; } if ( !command_data_asset->CanBeExecuted() ) { UE_LOG( LogSQ, Warning, TEXT( "The command %s can not be executed." ), *command_data_asset->GetClass()->GetFName().ToString() ); return false; } LastCommandDataAsset = command_data_asset; auto * command = command_data_asset->CreateCommand( *this ); return CommandManagerComponent->ExecuteCommand( command ); } To finish this part, here is the implementation of the command data asset used to register a game block in the level: USQCommand * USQCommandDataAssetAddGameBlock::CreateCommand( ASQLevelEditor & level_editor ) const { if ( !ensure( GameBlockClass != nullptr ) ) { return nullptr; } // Get needed informations, like the cursor position, the current displayed color, and so on… // Early return if we want to register a game block on coordinates which already has the same game block if ( tile_infos.Block->IsA( GameBlockClass ) && tile_infos.BlockPivotCoords == coords ) { return nullptr; } // Spawn the game block auto * game_block = level_editor.GetWorld()->SpawnActor< ASQGameBlock >( GameBlockClass ); // … and initialize it // Fill the array with all the coordinates the new game block will cover (some blocks are larger than a single tile) TArray< FSQCoords > used_coords_array; game_block->GetUsedTileCoords( used_coords_array ); const auto opposite_color = USQHelperLibrary::GetOppositeColor( world_color ); auto * command = NewObject< USQCommandComposite >( game_mode ); command->Initialize( "AddGameBlock", coords ); // For each coordinate used by the new game block, unregister the existing block FillCompositeCommandWithUnsetCoords( *command, *tile_manager, used_coords_array, opposite_color ); auto * set_game_block_command = NewObject< USQCommandRegisterBlock >( game_mode ); set_game_block_command->Initialize( coords, *game_block ); // Finally, register the game block command->AddCommand( *set_game_block_command ); game_block->FillCreationCommand( *command ); return command; }  As you can see, there is a lot more logic than inside the various commands, because here, we take care of all the steps needed to execute a final command. As mentioned in the first part, the model does not perform any logic related to the integrity of its data. It?EUR(TM)s then up to the command generator to make sure for example that all the coordinates of the grid which will be covered by a new game block are first cleared up. This can expand quickly, because maybe one of the coordinates to clear is part of another game block. Then the complete game block must be removed too. But as we can not leave holes in the grid, we must in a last step fill the holes left by removing this game block, but not covered by the game block we want to add, by basic blocks. This gets really hefty in the command generator which allows to resize the level, as you can imagine. And this is where being able to unit-test the model comes in very handy. (VERY!) That?EUR(TM)s all for today?EUR(TM)s article. We hope you found it useful, and helped you understand a few of the systems we currently use inside our game.

Report Article

## User Feedback

There are no comments to display.

## Create an account

Register a new account

• 0
• 23
• 0
• 1
• 0

• 26
• 10
• 9
• 9
• 11
• ### Similar Content

• Hey everyone! My name is Ryan.

Visualistic Studios is looking for experienced developers of all talents to join a game development team focused on completing contract work for compensation.

Work Description
Typically you will either be assisting the team or working on your own contract.
We usually bid $16-$25/h, however contracts can go above and below that so all pay grades are welcome, just be realistic.

Short Term Contracts
Long Term Contracts

We have the highest priority for these skills right now

Programming - Unity, Unreal Blueprints
Environment Artist
Character Artist
Character Animation
UI Artist
3D Asset Optimization

VR/Mobile experience is a plus.

The Process
All communication is done through discord. All tasks and design documents will be laid out in "HackNPlan" for organization.
Initially, you'll get in contact with me and answer a few questions so I can get a scope of your experience. Afterwards, our outreach team will start looking for jobs that fit your description. Nothing is guaranteed, but if we know you're interested we can start looking

Our Experience
For the past 3 years I've been working in game development contracting, and the past year I've been working full time from home. Since then, I've received more and more contracts and I'm now at the point that I have too many for myself to handle. This sparked the idea of creating a game development team for contract work! I've also been running my own hobby company for 5 years, and have a lot of experience in team management.

Get in contact!
Please fill out this form so we can get all of the information out of the way, then we'll get in contact with you!
Thank you everyone for reading, hope to hear from you soon!

• I am curious, if anyone would be interested in an RPG Adventure in a visual novel art style?
I loved Doki Doki and if I could create something in an RPG element, that would be THE BEST.
I am a complete noob however, that is the thing. Like I just started adventuring into coding two weeks ago. I love it so far.
I think I may be addicted. oof. Which is why I want to create something I have that itch. lol.
Basically if anyone who wants to pitch in for free, or not I'd be glad to include them in the credits section.
Also, I'd love to get the community involved in this, to create more fun RPG-esk things if that makes sense.
Where would I go for that?
• By komires
We are pleased to announce the release of Matali Physics 4.4. The latest version introduces comprehensive support for Android 9.0 Pie, iOS 12.x and macOS Mojave (version 10.14.x). Latest version also introduces Matali Render 3.4 add-on with normal mapping and parallax mapping based on the distance from the observer as well as other improvements and fixes.
What is Matali Physics?
Matali Physics is an advanced, multi-platform, high-performance 3d physics engine intended for games, virtual reality and physics-based simulations. Matali Physics and add-ons form physics environment which provides complex physical simulation and physics-based modeling of objects both real and imagined.
Main benefits of using Matali Physics:
Stable, high-performance solution supplied together with the rich set of add-ons for all major mobile and desktop platforms (both 32 and 64 bit)  Advanced samples ready to use in your own games  New features on request  Dedicated technical support  Regular updates and fixes

View full story

• I'm what you might consider a "casual prosumer" when it comes to commenting. I comment important stuff, but only if the code isn't written in a self-explanatory way. Which is why I've also adapted a really simple and descriptive naming scheme and done away with any and all notation systems.
That being said, there are occasions where I want to either document a whole system of code or provide a summarized walk-through on a per-function basis. This is where I find myself in a frustrating spot since none of the solutions on the market seem to be quite for what I want. So I figured I'd list things I want to achieve and what I want to avoid in hopes that I'm either not familiar with something or perhaps am simply not configuring stuff properly.
I'm willing to pay for a good solution.
The dream wish list of things I want and need:
full documentation generation, a la Doxygen a non-verbose (lightweight) and non-monolithic style non-XML style markup (eg the way Natural Docs does it, not Doxygen) no block comments in documentation (I use block comments extensively to manage code flow during development) partial documentation (I really don't want to provide an explanation for each and every argument and return type) a concise format with a clear layout, so no \param and \return shenanigans automatically filled in for me no duplication of obvious information (eg the function name) in the comments inline documentation no explicit flow direction (in/out/inout) in documentation, but rather taken directly from code - I already provide this information! proper macro expansion I've tried Atomineer and it doesn't work for me at all. So far the Doxygen style in general is pure bloat in my eyes since it becomes bothersome to maintain as soon as you make something as simple as a name change. Allow me to demonstrate by example:
Here's what a typical function in my code might look like:
_BASEMETHOD ECBool OnInitialize( IN MODIFY ResourceType& object, IN const char* type, OPTIONAL IN ISignalable* signalable = nullptr, OPTIONAL IN uint32 flags = 0) const { ... } _BASEMETHOD expands to 'virtual'. Atomineer doesn't handle this too well since it is adamant about placing the documentation below that line unless I take care to actually generate it on the word _BASEMETHOD itself.
Here's the default "trite" Atomineer generates:
/// Executes the initialize action /// /// \author yomama /// \date 12-Dec-18 /// /// \tparam ResourceType Type of the resource type. /// \param [in,out] {IN MODIFY ResourceType&} object The object. /// \param {IN const char*} type The type. /// \param [in,out] {OPTIONAL IN ISignalable*} signalable (Optional) If non-null, the signalable. /// \param {OPTIONAL IN uint32} custHandlerFlags The customer handler flags. /// /// \return {ECBool} An ECBool. This is close to being the least useful way to say what the function actually does. None of the auto-generated stuff makes sense, because it's already obvious from the names. In addition, data flow direction is assumed, not extrapolated from markup that already exists in the code (notice the in/out of signalable while certain conditions might force me to accept a non-const pointer, which is nevertheless never written to). The return type is obvious. Even the general description is obvious to the point of being insulting to the reader.
Of course this is all meant to be manually edited. However, the problem is that:
1) on the one hand, writing this stuff from scratch using this style of markup is time consuming and annoyingly verbose.
2) auto-generating the template and editing is also time consuming, because again, it's way too verbose.
Here's what an ideal way of commenting the above function looks to me:
/// Fill \p object with data and notify \p signalable once the procedure is complete. Runs asynchronously. _BASEMETHOD ECBool OnInitialize( IN MODIFY ResourceType& object, IN const char* type, OPTIONAL IN ISignalable* signalable = nullptr, /// Type-specific flags. See documentation of related resource type for possible values. OPTIONAL IN uint32 flags = 0) const { ... } That's it. This should be enough to generate feature-complete documentation when the docs are finally built. AND it's easy to read inline while writing code.
A major hurdle is that while I actually kinda like the Natural Docs style, to the best of my knowledge it's only able to generate documentation for things that have actually been manually documented. Facepalm. So no automatic full documentation of classes, inheritance diagrams, etc. This seemingly forces me into using Doxygen, which is much more feature complete, but suffers from the abovementioned stylistic bloat and for some reason cannot handle relatively simple macro expansions in imo-not-so-complicated cases. I simplified the following from a real world example, but this includes auto-generated class implementations, eg:
BEGIN_DEFAULT_HANDLER(foo) _BASEMETHOD const char* bar() const _OVERRIDE { return "yomama"; } END_DEFAULT_HANDLER(foo) which might expand into something like ---------> class foo : public crpt_base<foo> { base_interface* GetInterfaceClass() const _OVERRIDE { _STATIC foo_interface if; return &if; } _BASEMETHOD const char* bar() const _OVERRIDE { return "yomama"; } }; extern "C" _DLLEXPORT base_class* _fooFactory() { return static_cast<base_class*>(new foo); } Doxygen doesn't even recognize foo as a class.
The bottom line is it seems to me I shouldn't be asking for too much here. I'd really like the clear coding style I've adopted to pay off in more than just the code.
What's your approach? Any suggestions? Ideas or alternative options to explore?
• By komires
We are pleased to announce the release of Matali Physics 4.4. The latest version introduces comprehensive support for Android 9.0 Pie, iOS 12.x and macOS Mojave (version 10.14.x). Latest version also introduces Matali Render 3.4 add-on with normal mapping and parallax mapping based on the distance from the observer as well as other improvements and fixes.
What is Matali Physics?
Matali Physics is an advanced, multi-platform, high-performance 3d physics engine intended for games, virtual reality and physics-based simulations. Matali Physics and add-ons form physics environment which provides complex physical simulation and physics-based modeling of objects both real and imagined.
Main benefits of using Matali Physics:
Stable, high-performance solution supplied together with the rich set of add-ons for all major mobile and desktop platforms (both 32 and 64 bit)  Advanced samples ready to use in your own games  New features on request  Dedicated technical support  Regular updates and fixes