Concrete Architecture of SuperTuxKart

Concrete Architecture of SuperTuxKart Team Neo-Tux Latifa Azzam - 10100517 Zainab Bello - 10147946 Yuen Ting Lai (Phoebe) - 10145704 Jia Yue Sun (Selena) - 10152968 Shirley (Xue) Xiao - 10145624 Wanyu Zhang - 10141510 1

ABSTRACT This report outlines our concrete architecture of SuperTuxKart. The main points touched in this paper include our modification of our conceptual architecture of the game, the derivation process of the concrete architecture, the use of the reflexion analysis model to guide the investigation process of the unexpected dependencies discovered, in-depth analysis of two of our architecture s subsystems, walkthrough of a sequence diagram, observed design patterns, and lessons learned. SuperTuxKart s source code components were mapped into our original conceptual architecture s subsystems according to their expected functions. Three new subsystems were added in order to logically map the components into appropriate subsystems. We modeled the final architecture to have 8 subsystems: Input System, Controller, Game-specific Subsystems, Gameplay Foundations, Network, Utils, Library and Output System. Our initial architectural structure was layered then we modified it into an Object-Oriented structure in order to minimize the dependencies among the subsystems. We also identified the composite design pattern during the analysis of the config component in the Controller subsystem. The pattern enabled easy addition and removal of elements to and from the config component. 2

TABLE OF CONTENTS 1. Introduction and Overview 2. Conceptual Architecture 2.1. Modifications of Conceptual Architecture 2.2. Comparisons between Original and Modified Conceptual Architecture 3. Concrete Architecture 3.1. Derivation Process 3.2. Unexpected Dependencies 3.3. Description of high level architecture 3.4. Description of subsystems and interactions 4. Subsystem Analysis: Controller 5. Subsystem Analysis: Gameplay Foundations 6. Design Pattern - Composite 7. Concurrency 8. Sequence Diagram 9. Development Team Issues 10. Limitations of Reported Findings and the Problems We Faced 11. Lesson Learned 12. Conclusion 13. References 3

1. INTRODUCTION AND OVERVIEW SuperTuxKart also known as STK, is a free and open-source kart racing game initially released in 2004. STK s architecture continues to be interesting to analyze and this becomes more evident as we look closer at the source code, made available through the course webpage. We revised our conceptual architecture from the first assignment and mapped the components of SuperTuxKart s source code into subsystems (through the use of code analysis tool - Understand) to create the game s concrete architecture. While initially expecting a layered structure, the Understand tool demonstrated that the subsystems could be better fitted into an object-oriented style. We then used the Reflexion Analysis process as a guide during our investigations on the differences between our conceptual and concrete architectures. We also carried an in-depth analysis of the Controller and Gameplay Foundations subsystems. The dependencies amongst each subsystems components with the rest of the architecture were also explored alongside the dependencies within each subsystem. Constructing SuperTuxKart s concrete architecture did come with challenges however, we were able to overcome them and also learn a lot from the process. 2. CONCEPTUAL ARCHITECTURE 2.1. Modification of Conceptual Architecture Original Conceptual Architecture from the first Assignment With the aid of the Understand tool, we were able to analyze SuperTuxKart s source code by mapping the source code components into each of the subsystems in our conceptual architecture. During this process we discovered some components that we did not anticipate during the derivation of the game s conceptual architecture in the first assignment. These components include addons, config, font, replay, tinygettext and util. Although we were able to map most of the components, three new subsystems were added to the architecture in order to complete the logical mapping of the components. 4

The Network and Library subsystems were added to the architecture and we replaced the Core System with the Utils subsystem. In addition, we removed the Platform Independence Layer from the structure because we decided that none of the source code components could be logically mapped into it. After mapping the source code s components, we changed the structure of our architecture from a layered style to an object-oriented style. Finally, we modified our conceptual architecture diagram to reflect the modifications made. Modified Conceptual Architecture 2.2. Comparisons between Original and Modified Conceptual Architecture We changed the structure of our Conceptual architecture for SuperTuxKart from a Layered Style to an Object-Oriented Style. The reason for this change was to effectively represent the dependencies amongst the subsystems. As identified in the first assignment, our original conceptual architecture had low cohesion and low coupling amongst its components. However, with the modification of the architecture into object-oriented style the structure now has high cohesion and high coupling. It has high cohesion because the new subsystems added were able to reduce the amount of functionalities carried out by each component of the architecture. 3. CONCRETE ARCHITECTURE 3.1. Derivation Process We derived the concrete architecture of SuperTuxKart through the use of the Understand tool and the Reflexion Analysis model. Understand is a code analysis tool used to analyze and visualize a program s source code. Using our conceptual architecture as a guide, we mapped the game s source code components into the conceptual subsystems. From this, we were able to derive our first sketch of the concrete architecture. 5

Reflexion Analysis With the initial mapping of the source code components, there were a lot of dependencies between the architecture subsystems than we anticipated. Some of these connections were rational, while others were illogical. So we decided to re-group the components in each subsystem in order to improve the coupling and minimize the dependencies among the subsystems. For the second mapping, within the Gameplay Foundations we created the Graphics component to be composed of the modules that deal with the creation of the game s graphics. We grouped the animations, font, graphics and guiengine into this component. With this new mapping, the team was able to produce a concrete architecture for SuperTuxKart. Next we analyzed the code to understand how each subsystem functioned as well as the rationale behind the unexpected dependencies found in the architecture. 3.2. Unexpected Dependencies A fair share of the dependencies in our architecture were logical and easily predicted. However, there were some dependencies that were not anticipated. Upon further investigation they seemed intuitive and we ought to have expected them. Conceptual Architecture Concrete Architecture 6

Controller and Game-Specific Subsystems The first dependency to be investigated is the Controller depending on the Game-Specific Subsystem. The controller depends on the game-specific for over seven hundred class calls and this makes logical sense considering the game-specific subsystem is responsible for the objects in the game. The challenges in the controller calls on the karts component of the game-specific subsystems to unlock a specific kart whenever the player completes a challenge. The controller also contains the modes which depends on the game-specific tracks, karts, and items to obtain the track objects for the world frame. Replay in the controller depends on karts and tracks to obtain the replay event information. The game also has the config component in the controller using the constkconfig() method to call the KartProperties class in the game-specific to initialize a kart object. Also, race in the controller depends on karts and tracks to get the number of tracks from getnumberoftracks(). Game-Specific Subsystems and Gameplay Foundations The next unexpected dependency to be discussed is the Game-Specific Subsystems depending on the Gameplay Foundations. The karts in the game-specific depends on every component in gameplay apart from the scriptengine. An example would be when a kart produces a sound such as a beep sound by accessing the sound file in gameplay. Also, the tracks component in the game-specific subsystem depends on all of gameplay s components except the font module. For instance, tracks calls graphics to set the tracks materials texture and color. Output System and Game-Specific Subsystem The final unexpected dependency is the Output System depending on the Game-Specific Subsystems. There are over six hundred class calls from the output to the game-specific subsystem. Output mainly depends on the tracks and karts components of the game-specific subsystems. This is seen when the state_screens calls tracks to display the name of the kart next to it. For a player that's the name of the player, and for an AI kart it's the name of the driver. 3.3. Description of high level architecture The concrete architecture consists of eight subsystem: the Input System, Controller, Game-specific subsystems, Gameplay Foundations, Utils, Library, Network, and Output System. The two main components of our architecture are the Controller and the Gameplay Foundations. The Controller contains the achievements, challenges, config, modes, race, and replay modules. It is responsible for distributing input to the appropriate subsystems and also storing player information, such as the player s achievements. The Gameplay Foundations contains audio, graphics, physics, and scriptengine modules. It is responsible for providing the core facilities upon which game-specific logic can be implemented (Jason Gregory, 2009). 7

Concrete Architecture: Object-Oriented Style 3.4. Description of subsystems and interactions Input system The Input System s components consist of the game s input and io. IO transfer data to or from a computer. Input is responsible for obtaining input from the user. IO depends on the game s input in order to process raw data from it before sending it to the controller subsystem. Although the Input system depends on the library, it also has bidirectional dependencies with all the other subsystems in the architecture apart from the library. Controller The Controller in the concrete architecture has six components: race, mode, config, achievements, challenges, and replay. Controller is responsible for distributing data to the appropriate subsystems depending on the user s input. It also stores data of the challenges in the game and player s achievements. The controller has bidirectional dependencies with the other subsystems which was unexpected but logical. For example, if a player chooses a challenge under the story mode, the controller needs to communicate with the game-specific subsystems. This interaction is needed to obtain the kart s status, set up the race data in connection with the network interface, and interact with the gameplay foundations to build the game world. It also depends on the Physics subsystem to control the collisions of objects in the game. Once a challenge is completed, the game-specific subsystem generates the race results and updates the challenge status. At last, the Output system displays the proper trophy for the players. Game-specific Subsystems The components of the game-specific subsystems include items, karts, and tracks. It communicates with the other subsystems and updates its subcomponents as required. The game-specific depends on the gameplay foundations for the items module that contains the powerups obtained from giftboxes. The items modules defines the various collectibles of SuperTuxKart such as the powerups. The karts module contains the 3D Kart model and the 8

properties of the karts. It also contains several animations such as the rescue animation for a specific kart and the explosion animation that sends the kart into the air. The tracks modules contains information about the various tracks in the game such as the game s terrain information. Gameplay Foundations The components of the gameplay foundations are the audio, physics, graphics, and scriptengine. The Gameplay subsystem has two-way dependencies with the input system, controller, game-specific, network, utils, library, and output system. The audio module controls the sounds of the game while the physics and graphics depend on one another to show the collisions of the objects in the game. The scriptengine is responsible for the game code. The physics and graphics in the Gameplay communicates with the kart component in the game-specific foundations to choose and load a power up into the kart. Also the karts in the controller subsystem is dependent on the audio to make a beep sound when a kart collides with an object in the game. Utils The Utils subsystem in our concrete architecture contains the utils and tinygettext components. The utils component provides facilities such as crash report logs, game debugging, management of protocols at runtime and utilities for strings, tuples and vectors. Tinygettext handles the language options component of the SuperTuxKart. Several language options - created from the language and country code chosen by the user - are made available in the game. Tinygettext and utils are coupled together because of the language module in both components. The architecture also has a one-way dependency between the utils and the library, and two-way dependencies with every other subsystem (excluding the library) and the utils. Library The Library is a collection of precompiled routines used in the game. SuperTuxKart s library consists of components such as bullet collision and dynamics, the irrlicht engine, angelscript, and zlib. The bullet collision and dynamics is a physics engine that simulates collision detection of the game objects. The irrlicht engine is used to create the 3D graphics of the game such as the game s GUI, while Angelscript is the scripting language used in the game. The library also contains the zlib module which acts an archive, much like a ZIP or tar file, containing object files. It permits a large number of object files to be collected and compressed into a single easy-to-use file. All the subsystems in the architecture depend on this component. Network The Network Subsystem contains three main modules: the network, addons, and online. Network is responsible for processing a player profile and storing online related properties (if this is a server or a host, name of the server, IP address, etc.). Addons contains a selection of different downloadable extensions to be incorporated into the game. The Online module is responsible for HTTP(S) requests, the sign in process of players, and adding/checking of player profiles to cache. This subsystem interacts with every subsystem. It has a one way dependency to Util and Library and two way dependencies with the controller, game-specifics, gameplay, input system, and output system. 9

Output System The Output system contains the game state_screens. It is responsible for generating output depending on the player s input. Output has bidirectional dependencies to all other subsystems in the architecture apart from the Library. However, there exists a single arrow dependency between the Output and the library subsystem. 4. SUBSYSTEM ANALYSIS: CONTROLLER We defined the Controller as one of the main subsystems of SuperTuxKart s concrete architecture. It obtains data from the input system and distributes it to the appropriate subsystems. It also stores the player information such as the attained high scores, achievements, and game replays. As seen in the figure below, the main components of the controller are race, modes, achievements, config, challenges, and replay. The controller has bidirectional dependencies with all other subsystems except the library. We didn t expect this subsystem to be highly coupled with the other subsystems in our architecture but after conducting an in-depth analysis into it, we found the dependencies to be rational. Dependencies within the Controller Subsystem Race and modes are the two main modules of this subsystem. They obtain data from the player through the input system. They also interact with the output system to display the game s status, such as the start of a new race, the end of a current race, or the switching between game modes. Race contains the game update methods that call on the modules within the game-specific subsystems to obtain race information like the number of laps or the number of karts in a current race. Mode is tightly coupled with the game-specific subsystems as well because different items are required to build different game worlds that are stored in game-specific subsystem. The gameplay foundations deals with the creation of the actual graphics for world building and race setup based on the data sent into it from the controller. The replay module contains the functions for recording games to be replayed later on. Replay communicates with the game-specific subsystems to update the kart type and item s (e.g the banana peel) status. The config module includes the hardware configuration, sdk 10

configuration, and user configuration. Gameplay foundations needs to verify with these configurations when loading the game s audio or graphics. The Network also calls config over a hundred times to obtain the player s IP address and to update the client-lobby room. Challenges verifies with the gameplay foundations to see if a certain challenge has been unlocked or not. Furthermore, it also checks with game-specific subsystem for the status of the game karts, detailed challenge type etc. Output has a lot of calls to challenges, the most frequent use is the class that adds the proper trophy after different levels of a challenge has been completed. The Output System calls on the achievements module through the use of the online_profile_achievements.cpp class to obtain data like the player s name, ID, progress and so on. To conclude, the controller deals with majority of the logic in SuperTuxKart. Therefore, the high coupled interactions between the controller and other subsystems are logical and acceptable. 5. SUBSYSTEM ANALYSIS: GAMEPLAY FOUNDATIONS Dependencies within the Gameplay Foundations The main components of the Gameplay Foundations are the graphics, physics, scriptengine, and audio. The graphics contain the animations, guiengine, fonts, and the game s graphics modules. There exists certain interactions between the components of the gameplay foundations. The physics communicates with the graphics whenever objects collide with one another in the game world, for example a kart hitting a gift box or another game kart. The graphics also interacts with the audio component to provide sound effects at appropriate times in the game for instance, when a kart hits a gift box. The scriptengine depends on the graphics to display the game challenges and to also freeze the game s graphics whenever the game is paused. The graphics interacts with Controller to get the images and animations to be displayed in the different game modes. The graphics component also interacts with the controller to replace, 11

reset, and push graphics onto the output system whenever a cutscene occurs. The physics component interacts with the controller subsystem, particularly its mode components. An example of this interaction is seen when the kart s brakes are released at the start of a game. Physics also interacts with the game-specific subsystem to create the motion properties of the game karts. The audio component and game-specific subsystem interact with one another to create sounds in the game kart, for example the kart s engine sound. It also interacts with Controller to get the current music in the game world. The scriptengine loads and runs the game s code. The states_screens within the Output System uses the PropertyAnimator.cpp class from the scriptengine. When the player finishes a race the kart will no longer be available in the cutscene where the time results are shown. Furthermore, scriptengine interacts with the game-specific subsystem to monitor the movements of objects on the game s tracks with the track_object.cpp class calling the scriptengine to get the position of the objects in order to preserve their scale and rotation. 6. DESIGN PATTERN With the use of the lecture slides and the analysis of supertuxkart s documentation, we were able to identify the composite design pattern from the game s source code. A composite pattern is used to "compose" objects into tree structures in order to represent part-whole hierarchies. In the configuration component located in our Controller subsystem, we have the UserConfigParam which composes its elements as a tree structure as shown in the diagram below. This is to enable quick addition and removal of elements to and from the configuration system. Observer pattern identified in SuperTuxKart s source code 7. CONCURRENCY Concurrency in SuperTuxKart includes multiple computations performed at the same time. When a player starts playing the game, the game aspects of SuperTuxKart, such as graphics and audio are executed simultaneously. The graphics and audio also work in correlation to one another. For instance, when the player hits a banana a sound effect uh-oh is played to notify the player that they have obtained something that would not benefit them. Another 12

example of concurrency is the physics existing concurrently with animations. This occurs when the swatter requires the calculation of the angle at which the kart will be flattened. The two components also create the kart s motion space in the 3D world. 8. SEQUENCE DIAGRAM Scenario: A local player drives a kart and hits a banana peel on the track This scenario describes what happens after a local player s kart hits a banana peel on the track. In our sequence diagram, the item_manager class calls item->collected(kart) function from the item class. This function sets a flag to indicate that an item has been collected. The item class then returns the time for the duration of the anvil to be attached to the kart. Next, the item_manager class calls the Kart->collectedItem(item, add_info) function from the karts class to add the collected item onto the player s kart. The attachment class then identifies the item as a banana and checks with the getcontroller()->cangetachievement from the attachment class to see if the achievement can be obtained or not depending on if the game is being played by a local player. In this scenario, it returns true because the game is being played by a local player. The attachment class then updates the achievements of the local player through the increaseachievement(achieveinfo::achieve_banana, banana, 1) class in the controller subsystem. After increasing the points for an achievement, the speed and the weight of the player s kart increases due to the weight of the anvil. 9. DEVELOPMENT TEAM ISSUES SuperTuxKart s architecture isn t easily modifiable due to the high degree of dependencies amongst the subsystems. We noticed that if the team was to evolve a subsystem, it would cause a ripple effect across the architecture. This entails having to test and make changes to every other subsystem. Another issue faced by the team was the large number of unfinished work by contributing developers to the game. 13

10. LIMITATION OF REPORTED FINDINGS AND THE PROBLEMS WE FACED There were a couple of limitations in our reported findings for SuperTuxKart s concrete architecture. First of all, the game s source code was not well documented making it a bit difficult to understand some of the relationships between the subsystems. The Understand tool also crashes from time to time due to bugs present in the system. Furthermore, Understand gives an unclear representation of the dependencies between the concrete architecture s subsystems. The order of the calls between subsystems differs from when you display the high level architecture showing all the dependencies and when we highlight a particular subsystem to look at the edges coming into it. For example, in fig 1 below, the output system calls the utils 6 times. However, in fig 2 when the utils subsystem is highlighted to show edges coming into it, the order of calls between the systems is switched i.e utils now calls the output system 6 times. Fig 1. High level Architecture without the use of the Understand tool feature Fig 2. High level architecture with feature of looking at the edges going into the Utils Subsystem 11. LESSONS LEARNED We learned during our derivation process that Understand is an efficient tool for analyzing source codes. Our original conceptual architecture did not take into account some of the major components of a game s architecture such as the utils subsystem. Because of this, the initial mapping of the subsystems had a couple of illogical dependencies among the subsystems but after refining our architecture, we were able to minimize the dependencies. We were also able to identify the observer design pattern from the game s source code through the use of the lecture materials and the developer s documentation. Our final lesson learned was that we should have analyzed the sequence diagram whilst analyzing the concrete architecture through the use of the source code. This would have saved us time and improved the team s efficiency in developing the sequence diagram. 14

12. CONCLUSION To conclude, our conceptual architecture was changed from a Layered to Object-Oriented structure. This modification was made due to the additional dependencies and components obtained from the mapping of the game s source code using the Understand tool. The tool was essential for the extraction SuperTuxKart s concrete architecture and analysis of the architecture s subsystems. The revised conceptual architecture and the concrete architecture both have high-coupling and high cohesion. High cohesion because the new subsystems added were able to minimize the amount of functionalities carried out by each component of the architecture. High coupling because of the various dependencies between the high level subsystems. 13. REFERENCES Runtime Engine Architecture. (n.d.). Retrieved from http://frost.ics.uci.edu/ics161/runtimeenginearchtecture.pdf A. (n.d.). Developer interview: SuperTuxKart team Retrieved from http://freegamer.blogspot.ca/2012/02/developer-interview-supertuxkart-team.html G. Bufardeci (n.d.). Concrete Architecture and Reflexion Analysis Retrieved from https://cisc326.files.wordpress.com/2015/10/cisc326a2-report-docx.pdf 15