Game Definition DSL

The game definition DSL is one of the most important visual languages of the ArcadEx factory. The picture below presents some of its features:

  • The main visual editor enables game developers and designers to work in a higher abstraction level, by specifying game screens and other properties through a diagram.
  • The Toolbox at the right enables a dragging-and-dropping game development experience for routine tasks (such as adding new screens, connecting screens, etc.).
  • The Properties Window enables editing properties of the game and its elements. Richer property editors (such as for defining screen transition triggers) are supported. The Properties Window is also integrated with the XNA Content subproject: when new textures and sounds are added to the project, the game developer/designer will be able to pick them from the Properties Window.
  • The Error List validates the designed diagram and guides the game developer/designer, showing high-level game design errors and moving focus, after a double-click, to the diagram element which has problems.
  • Code generators can be launched to generate the game code from the design diagram.

Please notice: you'll need to have the Input Mapping DSL installed to properly design diagrams using the Game Definition DSL.

Tutorial: Designing a game from scratch using the Game Definition DSL

(get the final code here:

This tutorial is similar to the video below (best viewed in full screen; click in "Launch in another window" and full screen from there)"

1. Open Visual Studio, then proceed to the File -> New Project menu. Choose the ArcadEx Game project template, then enter the game name (I'll call it DemoGame).


2. A new ArcadEx solution will be loaded, and two files will be opened in the Visual Studio main window:
  • where you design your game. Notice that, by default, your game already comes with a Start Screen and a Credits Screen, which are alternately shown to players at each five seconds. You can edit those if you want, but for now we'll leave them the way they are.
  • DefaultInputmapping.inputmapping: the default input mapping (from Xbox360 controller buttons to keyboard keys) for the game.


3. Let's try running the game to see what happens. The first time you run the game and every time you make a change to any of the designers above, you need to click on the Transform All Templates button in the Solution Explorer (see picture below) to launch the code generation. After that, compile and run the game.


4. Our default "Hello World" game (not really a game yet, you know) will appear. As you wait five seconds, the Credits Screen will appear. Wait 5 seconds again, then you'll be brought back to the Start Screen. Press the ESC key in your keyboard to exit.


5. Back to the designer, click in any blank area then check the Properties Window. You can see some game properties, such as its name, resolution, namespace and others. Change the Resolution from (800,600) to (640,480), and then change the Window Mode from Windowed to FullScreen. Click in Transform All Templates again then re-run your game to check the changes.

  • Note1: you won't be able to see the game in full screen if you enter a resolution that is not supported for full screen mode by your graphics card.
  • Note2: I suggest reverting back from FullScreen to the Windowed display mode before proceeding, for convenience when debugging the game.

6. Rename the file in the Solution Explorer to The GameDefinitionDSL will ask whether you want to change the game Name property as well. Click in Yes.


7. Let's add a new screen to the game. Drag and drop the Screen entry from the Toolbox to the diagram, then do the same with the Transition entry to connect the Start Screen with the new screen. Rename the new screen to Main Screen.

  • Note: if the previous transition lines get messy when you add the new screen, just move the new screen around to make them come back to where they were before.

8. Right-click the diagram then select Validate All. The Visual Studio Error List will tell you that the new transition you added should have a trigger. Double-click the error to bring the transition to focus.


9. With the transition selected, go to the Properties Window and click in the "..." button. A new window will open for you to specify the transition trigger type and its properties. In our case, we'll want to transition from the Start Screen to the Main Screen when the Player1 presses the Start button in the Xbox360 controller. Click in OK and check the changes in the diagram.

  • Note: the transition button name may appear truncated in the diagram. In such a case, just move its target or source screen around and it'll be displayed properly,

10. Let's explore some of the screen properties. With the Main Screen in focus, check the Properties Window. First, let's define a background picture (texture) for the Main Screen. A drop down arrow will tell you what textures are already present in the Content\<TextureContentSubDirectory> game folder.

  • Note: the TextureContentSubDirectory folder path is actually a property of the Game and can be specified by you. Its default value is "Textures".

11. I'll be using three extra textures and one extra music file for this Demo Game. You can get them here:


12. In the Solution Explorer, notice the Content\Textures folder.


13. Right-click it then select Add -> Existing Item. Point to the bgMain.png file to have it copied to your project.


14. Now select the Main Screen again, go back to the Properties Window and click in the background picture drop down. The new bgMain asset will be there. Select it.

  • Note: at this point, you can re-generate code (Transform All Templates), re-compile and rerun the game to check how it's looking like.

15. Investigate now the Music Behavior of the Main Screen. The screen can keep playing the game current music, start a new music (case in which a Music Asset Name should be specified for the screen), stop the background music or inherit the behavior from its parent screen. For now, let's leave the Main Screen playing the current game music.


16. In our tutorial, there will be two possible ways for the game to end: Player1 wins or Player2 wins. We'll have one separate screen for each one of such possibilities, but since they share lots of common behavior (such as playing a new background music and navigating to the Main Screen if the Player1 presses the Start button), we'll create a base class to encapsulate such a behavior. Use the Toolbox items to add the screens and establish the inheritance relationships.


17. In the same way you added new textures to the game, add the mscEnd.wav music (from the same pack) to the Content\Audio subfolder. Then set the Music Asset Name of the End Screen accordingly. Its Music Behavior should be StartNew, and you can also specify whether its background music should be played in loop. Finally, set the Music Behavior of each one of the End Screen's children screens to Inherit.


18. Add the bgPlayer1Wins.png and bgPlayer2Wins.png files to your Content\Textures project folder, then update the Background Picture Asset Name names of the end child screens accordingly. Finally, connect the End Screen to the Main Screen through a "start button pressed" transition. Your diagram so far should look like this:


19. Add the transitions from the main screen to the child end screens (Player1/Player2 Wins Screen). This time, the let's make the transition triggers to be "custom method" triggers (called Player1WinsCheck and Player2WinsCheck) that will have to be implemented by game developers.


20. Re-generate the code (Transform All Templates) and try to compile the solution. Notice that the Error List will show errors stating that the methods Player1WinsCheck and Player2WinsCheck were not implemented.


21. Let's implement those methods. Add to your project a new class called MainScreen, then change its namespace from DemoGame to DemoGame.Screens (that's where the generated screens are implemented) and mark it as public partial. As you type override in the class body, you'll notice that the custom method names provided in the visual designer will be available there for you to override.


22. For the sake of simplicity, I'll implement a code that randomly attributes victory to the Player1 or to the Player2. In the real world, you would be defining game Entities in this Screen and performing other types of (real) checks, such as collision detection, player score checking, etc. Future DSLs of the ArcadEx factory will be specifically focused on raising the abstraction level of such task.


23. Finally, re-generate code, recompile and run your game. Feel free to extend it from here!
  • Three notes on player input:
    • In the game start screen (which is identified by a star), pressing the Back button in the Xbox 360 Controller or ESC in the keyboard will always exit the game.
    • The StandardMapping.inputmapping file, by default, maps the Back button in the Xbox 360 Controller to the ESC keyboard key, as well as the Start button in the Xbox 360 Controller to the ENTER keyboard key. In other words, the keyboard can still be used to play or test your game if a Xbox360 controller is not available. Such a file can be modified (for details, check the Input Mapping DSL).
    • You can add to your project additional input mapping files (right-click the project, then Add -> New Item -> Input Mapping). To apply to the game the mappings defined in such a new file, you just need to:
      • Add to your project a new partial class with the same name of the game (in our case, Demo).
      • Override its Initialize method, by calling base.Initialize() and <YourNewMapping>.ApplyMappings().


Happy gaming!
-- AFurtado

Last edited Mar 3, 2009 at 10:39 PM by AFurtado, version 15


No comments yet.