Skip to end of metadata
Go to start of metadata

Overview

In this tutorial, we will be adding a main menu UI to an existing game project, Galaxsys, using Schematyc. 

We recommend taking a look at the Creating and Implementing a Crosshair tutorial beforehand, since topics such as folder structure will not be covered in-depth in this tutorial.

Prerequisites  

  • CRYENGINE 5.7 LTS
  • Adobe Animate (any version)
  • A C++ editor of your choice (Visual Studio is recommended)
  • The Galaxsys Sample Project from the CRYENGINE Marketplace
  • Additional assets for this tutorial

Creating a Menu

The Galaxsys project does not have an in-game main menu, only a basic HUD that shows the score, the time, and a “Press Enter to Start” idle screen. We will be creating a working menu in Adobe Animate.

  • If you do not already have a basic menu with several buttons created, the menu used in this tutorial is provided in the tutorial’s asset pack.
  • Since menu creation in Adobe Animate is a somewhat in-depth process, this tutorial will not cover how to make a menu in Adobe Animate and assumes you will either use the menu provided, or have pre-created menu with several buttons.

During this tutorial, we will be adding UI functionality (via Action Script 3.0 and Schematyc) to several buttons and menu features:

  • Displaying the menu.
  • Mouse functionality in the menu.
  • Play button to start the game.
  • Mute button to mute the music.
  • Have the menu re-appear upon player death.

Adding Functions to the Play Button

A blank Menu asset was provided with this tutorial. We will use it to explain how Schematyc and Action Script can be applied to bridge the Menu with CRYENGINE. The provided menu does not contain logic, and while the buttons are animated, they do nothing when clicked on. 

You can download the additional assets from the Prerequisites section

In the first section of this tutorial, we will go over the Action Scripts that must be applied to these menu buttons in order for CRYENGINE to be able to understand the buttons' intended purpose. To start, we will add functionality to the Play button, so that upon clicking it, the game begins.

  1. In Adobe Animate, open the existing Menu.fla project that comes with the tutorial assets.

  2. With the project open in Adobe Animate, select the first frame in the project timeline. Open the Actions window with the F9 hotkey, or navigate to Window → Actions and add the following line:

    import flash.events.MouseEvent;
  3. Before applying any Action Script to the Play button, make sure to use the Selection Tool to click the Play button, which will be confirmed as selected when a blue rectangle appears around it. 


  4. With the Play button selected, in the Actions window on Frame 1, type out the following Action Script:

    playbut.addEventListener(MouseEvent.CLICK, Play);
    function Play(e:MouseEvent): void
    {
         if (ExternalInterface.available)  {
               ExternalInterface.call ("PlayButtonClicked");
    }
    The name PlayButtonClicked will be used later within the Menu.xml for event listening, and will be the same name we need to give our fsCommand within the .xml. This is due to ExternalInterface.call being called fsCommands in past versions of Flash.

    The first line contains playbut, the name we have for our play button instance in Adobe Animate. This is followed by an event listener that will carry out a function when we press the button (in this case, with a MouseEvent, i.e. a mouse click).

    It is important to give every button in Adobe Animate a unique instance name, this name will be referred to within your Action Script.

    The second line is the actual MouseEvent function, which we’ve given the name Play. This Play is the name of the AddEventListener. Within the brackets, we’ve designated that if our Play function is triggered, the playbut event will happen (in this case, start our game when we add Schematyc logic). 


  5. With this Action Script written into our menu, we can now export the menu in Adobe Animate. As also mentioned in the first tutorial, we will export our Menu.swf into the project’s UI/ folder and convert our Menu.swf into a Menu.gfx using the shortcut we created with our Scaleform4 Exporter Tool. 


  6. Once converted, the Menu.gfx should be in the UI/ folder. Within the UIElements folder, create a new text document named Menu.xml:

    The first section is the UIElements name, which can be considered as the category of your .xml. If you intend to add various .gfx to your .xml, this is a good way to stay organized, and give your .xml a categorical name: 


    The second section is the UIElement, which represents the name of a specific element. In this case, it is named GalaxsysMenu:

    This is also the name that will show up in Schematyc when you add the Flash Element component and nodes.

    The third section is GFx and its constraints. The GFx section should reflect the exact name of your GFx, including capitalization. In this case, it is recommended to name it Menu.gfx. This section includes the layer information, information about menu alignment, and a resolution:

    • The name within the file=”Menu.gfx” of the GFx line is case-sensitive, and needs to be exactly the same name as the GFx file you want the .xml to call upon.
    • It is recommended to use a resolution value (width and height) which matches the project resolution. 

    The next section is the events section. This section determines how Action Script communicates with CRYENGINE and tells CRYENGINE what event we called upon in the Action Script. In this case, event name=”Play” defines how the Signal/Component will show up in Schematyc, and the fsCommand name, which is also known as the ExternalInterface.call name.
     

    The name of the fsCommand line should reflect the name of the ExternalInterface.call name given in ActionScript, whereas the event name line is not reliant on any other sources and can be named whatever makes the most sense to you.
  7. Open the GalaxSys.cryproject in CRYENGINE 5.7 LTS folder.

  8. With the project open, hit CTRL+G to test the game. The default state of the game has the score, time and health appear on game start, as well as the Press Start or Enter text:


  9. Navigate to Tools → Deprecated → Schematyc Editor (Experimental) and navigate to the Asset Browser panel.

  10. In the Asset Browser, navigate to the Schematyc Entity titled game. This game Schematyc Entity is where most of the core elements of the game logic are, and home of the UI logic to be modified.

  11. With the game Schematyc Entity selected, navigate to the tab on the right, and click Script Browser. Under Graphs, select the Signal Graph to view the graph we will be working in.

    In order to add our own menu, we need to add the Menu as a Component.
  12. Next to the Script Browser tab, click Add, and select Component. In the search window that pops up, type in Menu and you should see the Galaxsys menu we added via the Menu.xml as a selectable option as FlashElement:GalaxysMenu: 

    • If you don’t see the FlashElement:GalaxysMenu as a selectable option, the problem is likely due to an error in the .xml.
    • Make sure you have all the correct opening/closing lines, the name of your .gfx in the GFx line is exactly the same as the Menu.gfx, and watch out for other slight errors such as a misplaced space or quotation marks.
    • Typing gfx_reload_all in CRYENGINE Console can help highlight the error and line the error is in, if it is caused by the .xml.
  13. With the GalaxsysMenu component added, locate the UI HUD: Dynamic::Set Visibility component node at the end of the first graph line, and delete it. 

  14. Right-click, and place a FlashElement:GalaxysMenu::Set Visible node. The checkbox for Visible property is ticked in its properties by default.

  15. In the UI HUD: Set Visibility node, untick the Visible property. Now you should see no score/time/health information but only the new menu on game start. 

  16. Connect the FlashElement:GalaxysMenu::Set Visible and UI HUD: Set Visibility nodes:


  17. Test the functionality by clicking CTRL+G and entering the game mode.

Adding a Mouse Cursor

After testing, you may have noticed that there is no mouse cursor to click any of the buttons with. Adding a cursor to your project can be achieved by adding two nodes into our Schematyc graph.

  1. Since we are replacing the default Enter key action to start the game in favor of the clickable mouse menu, first delete the three Input::RegisterActions nodes, and replace them with two FlashElement:GalaxysMenu::Set Instance Flag nodes.  

  2. In the properties of the first Set Instance Flag node, select Hardware Cursor for the Flag field under the Properties section. In the second, select Mouse Event for the Flag field. Make sure the Value property is ticked for both of their properties, then connect all the nodes in the first line.

    The first line of the game Schematyc Entity Signal Graph will now display a cursor and the menu, and make the score/health/time information invisible until the gameplay start.

Play Button Logic

The menu now shows up, along with a mouse cursor to click it with, but clicking the Play button still won’t start the game. You need to apply one last bit of logic in order for CRYENGINE to know that by clicking the button, you intend to start the game. Since the menu is added as a Component, you don’t need to add anything else, and just need to replace the default input signal with a signal that is tied to the intended component and the event.

  1. In the second line of the Signal Graph, delete the first node named Input::On Action Pressed. Right-click and place a FlashElement:GalaxsysMenu::Play signal in its place.

  2. Now delete the Equal and Branch nodes, and connect the Out pin of our FlashElement:GalaxsysMenu::Play node to the In pin of the Game Events::SendResetGame node: 


  3. We want to make sure that once we click the Play button, our menu disappears so that we can play the game without the menu in the way. In the second line, delete and replace the last node in the second line with a FlashElement:GalaxsysMenu::Set Visibility node, but this time, make sure Visible property is unticked.

  4. Test the game with CTRL+G. Clicking Play should start the game, hide the new menu and the previous menu with the score/time/health information:

Menu After Player Death

While the menu works as intended so far, it only shows up in the initial launch. We want to make sure that the menu comes back once the player has died, so that the player can click Play to try again.

  1. Place a FlashElement:GalaxsysMenu::Set Visibility node at the end of the 4th line of the game Signal Graph.

  2. Connect the Out pin of the existing Controllable Timer::Stop to the In pin of the new FlashElement:GalaxsysMenu::Set Visibility node and leave the Visible property ticked in its Properties panel.

Mute Button

Unlike the play button which has one state (to always play when clicked) the mute button’s objective has two states – to be able to both mute and unmute. While the functionality we will be applying is to mute/unmute the game, this technique can be used for a myriad of tasks - to anything you want to have a true/false state. While the Play button acted more like a button, this next Mute button is more of a switch.

However, before doing anything in CRYENGINE with Schematyc, we must add another ActionScript event to the Mute button in Adobe Animate.

  1. Open the Menu.fla project in Adobe Animate.

  2. On Frame 1 of the Menu project timeline in Adobe Animate, press F9 to open the Actions window, and add these lines for the MouseEvent:

    The script is identical to the first event for the Play button, with minor differences in the naming – play is now mute to match the instance names and button is now button1 to match the fscommand name in the .xml.
  3. Save and export the Menu.fla project as an .swf like before.

  4. Export the .swf into a GFx using the Scaleform4 Exporter Shortcut and replace the existing Menu.gfx in the /ui folder.

  5. Next, we need to update the Menu.xml within our ui/uielements folder to reflect our newly added ActionScript event. Copy and paste the existing play event line, and paste it underneath the existing one. You only need to change the event name for the name in Schematyc, and the fscommand to reflect our the name we gave our ExternalInterface.call line in ActionScript:



  6. Save the updated Menu.xml, and open CRYENGINE 5.7 LTS.

  7. In the Asset Browser, navigate to the Entities folder, and open the music Schematyc Entity.

  8. Click Add and add the FlashElement:GalaxsysMenu as a component into the music Schematyc entity:


  9. Navigate to the Signal Graph, right-click and add a FlashElement:GalaxysMenu::Mute signal to the graph and connect the nodes:

    The default Signal Graph makes the music always play upon game start and end on game stop/end with no option to mute it.
  10. We need to add a new Variable to our graph. Click the Add button in the Script Browser, and select Variable. Name the Variable isPlaying.

  11. In the music Signal Graph, add a Get[isPlaying] node, and attach its Value pin to the Value pin of the Branch node:


  12. Add a Trigger::Play node and attach it to the Branch node's True pin. Add a Trigger::Stop node and attach it to the Branch node's False pin:


  13. Add two Set[isPlaying] nodes and attach them to the added Trigger nodes. In the properties of the Set[isPlaying] node that is attached to the False Trigger::Stop node, make sure it has the Value ticked as False:


  14. Lastly, add a Trigger::Play node and attach it to the Start signal, as well as a Set[isPlaying] node and attach it to the Trigger:Play:


With this, you will be able to mute and unmute Galaxsys’ music upon clicking the Mute Music button on the menu.

Note that this functionality will likely not work in the Engine when testing with CTRL+G and should be tested via File → Export to Engine, then right-clicking the .cryproject file in the Windows Explorer and selecting the Launch Game option.



  • Within this graph, the music is playing by default at the game start: Start → Trigger::Play → Set [isMuted].
  • Once the Mute button is pressed, it checks to see if the music is playing or not: FlashElement:GalaxsysMenu::Mute → Branch → True/False Value.
  • Depending on the current state of the music, it will see if it is either true or false, and either stop or play the music. Upon testing the game, you should now have a mute switch, and can mute or unmute the music with the Mute Music button on the bottom-right corner.

Adding a Quit Function

By default, quitting the Galaxsys game can only be done by pressing ALT+F4 within the game console or via a quit function which exists as a game element. Now we will add both a Quit button event to the Galaxsys UI and an actual quit function into the source code of the game itself so that we can tie the button event and the new function together.

Before doing any C++, make sure to add the same MouseEvent function to the Quit button. Just like the first two buttons, this line of ActionScript looks the same other than the name of the event and the fscommand name.

  1. On Frame 1 of the Menu.fla project timeline in Adobe Animate, press F9, to open the Actions window, and add these lines for the MouseEvent:


  2. Save and export the Menu.fla project as an .swf like before.

  3. Export the .swf into a GFx using the Scaleform4 Exporter Shortcut and replace the existing Menu.gfx in the /ui folder.

  4. Next we need to update the Menu.xml within our ui/uielements folder to reflect our newly added ActionScript event. Copy and paste the existing play event line, and paste it underneath the existing one. You only need to change the event name for the name in Schematyc, and the fscommand to reflect our the name we gave our ExternalInterface.call line in ActionScript:


  5. Save the updated Menu.xml.

With the button event added, we need to access the source code of Galaxsys so we can create a game function to tie together with the new button event.

  1. In the Galaxsys main project folder, right-click on the Galaxsys.cryproject and select the Generate Solution option. A folder named solutions will appear in the project’s main directory.

  2. Within the main project directory, navigate to solutions\win64 and open GalaxSys.sln in Visual Studio.


  3. Before making any lines of code, make sure to change the Solution Configuration to Profile from the default Debug option. This can be found on the ribbon menu:


  4. With the GalaxSys.sln open, navigate to the GameFunctions.cpp, and scroll down to line 100.

  5. In line 100, write or copy and paste the following line:

    void QuitGame() {
    			gEnv->pConsole->ExecuteString("Quit");
    		}

    The functions of the strings presented above are as follows:
    • gEnv → Global variable.
    • pConsole → Provides access to the Console variables/commands.
    • ExecuteString("Quit") → Executes the specific quit console command.
  6. To reflect this line so it can show up in Schematyc, scroll down to line 212 within the same GameFunctions.cpp, and add the following lines:

    {
    	auto const pFunction = SCHEMATYC_MAKE_ENV_FUNCTION(&Game::QuitGame, "{XXXXXXX-XXXX-XXXX-XXXXXXXX}”_cry_guid, "QuitGame");
    	pFunction->SetDescription("this function quits the game");
    	scope.Register(pFunction);
    }
  7. In the Visual Studio, navigate to Tools → Create GUID and select the Registry Format option. Select Copy and close the pop-up window with exit. Paste the copied GUID in place of the “XXXXXXX-XXXX-XXXX-XXXXXXXX”:

    The line should look as shown in the following image: 


  8. Within the GalaxSys.sln, open the GameFunction.h (header) and scroll down to line 37. Add:

    void QuitGame(); 
  9. Save your progress and open the project, this time from Visual Studio by clicking the Local Windows Debugger option in the ribbon menu of the Visual Studio:


  10. Within the Galaxsys project, open the game Schematyc Entity, and open the Signal Graph.

  11. After the bottom line on the Signal Graph, right-click and add a FlashElement:GalaxsysMenu::Quit node.

  12. Right-click and add a QuitGame node.

  13. Connect the Out pin of the FlashElement:GalaxsysMenu::Quit node to the In pin of the QuitGame node:


  14. To test, click File → Export to Engine from the Sandbox Editor, then right-click your GalaxSys.cryproject file in the Windows Explorer and select Launch Game.

Conclusion

This concludes the tutorial. To learn more about the UI in CRYENGINE and/or other topics, please refer to the CRYENGINE V Manual.

Video Tutorial

You can also follow this tutorial series in video form on our YouTube channel. 




On This Page

  • No labels