Sensible Chuckle SuperTuxKart Concrete Architecture Report Sam Strike - 10152402 Ben Mitchell - 10151495

Alex Mersereau - 10152885 Will Gervais - 10056247 David Cho - 10056519

Michael Spiering

Table of Contents Abstract …………………………………...……………………...………………… Page 2 Architecture Derivation Process …………………………......………………... Page 2 Conceptual Architecture

● Original Conceptual Architecture ……………………………...………….. Page 3 ● Revised Conceptual Architecture ……………………………...…………. Page 3

Concrete Architecture ● Concrete Architecture Overview …………………………….…..………... Page 4 ● Conceptual Vs. Concrete ………………………………….…..…………... Page 4 ● Reflexion Analysis ………………………………………….…..…………... Page 5

Architecture Subsystems ● Game Specific Subsystems …………………………...……..…….……... Page 5 ● Graphics ……………………………………..………...…………………… Page 7 ● Controller ………………………………………………..………………….. Page 7 ● Physics ……………………………………………...…..………………….. Page 7 ● Audio ……………………………………………...…..……………………. Page 8 ● Core Systems ……………………………………......…………………….. Page 8 ● Network ……………………………………………..…..…………………. Page 9 ● Libraries ………………………………………….……..……………….... Page 10

Sequence Diagrams ● Sequence Diagram #1 …………………………………..…..………….... Page 10 ● Sequence Diagram #2 …………………………………...……………… Page 11

Concurrency …………………………………………………...………………... Page 11 Division of Responsibilities and Development Team Issues ……….…... Page 12 Lessons Learned ……………………………………………………...………... Page 12 Conclusion ……………………………………………………………………….. Page 12 References …………………………………………………………...………….. Page 13

Abstract

As a free, open-source game project, SuperTuxKart has seen a wide variety of talents and contributions since its release in 2004. A racing game created in the style of the Mario Kart series, SuperTuxKart has players controlling one of a multitude of “karts”, vehicles in which they race other player- or AI-controlled karts on various tracks.

As with any piece of software, SuperTuxKart ’s inner workings can be mapped to a layout known as a software architecture. In the previous assignment, we created a conceptual architecture based on what we thought SuperTuxKart ’s functionality would best fit. This time around, we utilized a program known as Understand to create a concrete architecture, drawing directly on the function calls and interconnectivity of SuperTuxKart ’s actual source code. We then compared both diagrams and did an analysis on their points of convergence and divergence. Architecture Derivation Process

The first step in the formulation of our concrete architecture was to evaluate our original conceptual architecture from assignment 1 and see if it still held, based on the feedback we received and our new ideas. We revised quite a few aspects, such as introducing the new subcomponents Core Systems and Controller, while eliminating User Interface and Player Manager, among others.

Once we were happy with this new layout, it was time to move from conceptual to concrete. We used Understand to map the source directories of SuperTuxKart to subcomponents in our conceptual architecture, and examined the resulting dependency graph. If we discovered dependencies between subcomponents that just didn’t make sense, we traced these connections back to their sources. We either re-mapped directories/files to different subcomponents that might produce more logical results, or we labelled said dependencies as unexpected in our comparison between our two architectures. The dependency graph was then re-examined, and the process was repeated until we felt that no further changes to our concrete architecture were necessary. The result of our efforts is pictured below.

Conceptual Architecture Original Conceptual Architecture

Revised Conceptual Architecture

Modifications we made to our original architecture include the removal of User Interface and the relocation of Player Manager to inside Game Specific Subsystems. We decided that our concept of User Interface in our original architecture was more of a hardware implementation, which did not fit inside the software architecture. We

also decided that the Player Manager was actually too low level; a component of a subsystem rather than its own subsystem. Furthermore, some of the features of Player Manager, such as achievements and config, have a close relationship with other components inside Game Specific Subsystems (and Network, which interacts with Game Specific Subsystems), so it made the most sense to combine the two. Concrete Architecture Concrete Architecture Overview

This is the outcome of our use of the Understand tool with our revised conceptual architecture as a baseline. Conceptual vs. Concrete

Conceptual Concrete

As shown in the diagram above, the concrete architecture consists of many unexpected dependencies that were defined from a source code level. We’ve taken a look at the origin of these dependencies to find the rationale behind such interactions, which are further explained in each subsystem’s section. Reflexion Analysis

Reflexion Analysis is a mechanism used to measure the differences between a conceptual architecture and a concrete architecture. This process allows one to define what is absent or misplaced between the architectures by examining the dependencies in the concrete architecture that were not anticipated in the conceptual architecture. This is then followed by an investigation of these unexpected dependencies to decide whether architectural changes need to be made. Architecture Subsystems Game Specific Subsystems

Game Specific Subsystems makes up the core of the gameplay entities that users interact with while playing SuperTuxKart . It stores information about the game state and properties about game objects, such as a kart's speed or weight. It also stores game unlocks and player scores.

An unexpected dependency that we found was that Game Specific Subsystems depended on Network. This is because, when an addon is downloaded from the Internet, the data contained in the addon must be loaded into the game files.

Game Specific Subsystems Internal View Game Specific Subsystems can be broken down into five subcomponents:

Game Structure, Game Objects, Player Management, Scripts and States. Game Structure consists of the race data and different race modes that help contribute to the overall gameplay of a race. Game Objects are the dynamic objects within the race world, such as karts, items, and tracks that are subject to change within the world. Player Management deals with all the achievements and challenges a user can unlock from the game. Scripts holds the script engines for all the dynamic game objects. Lastly, States handles all the various screens a user can encounter while playing SuperTuxKart .

By splitting Game Specific Subsystems into five subcomponents, each

subcomponent was dependent on each other, and coupling was very high. Game Specific Subsystems Full View

In the overall architecture, each subsystem is dependent on most of the five subcomponents within Game Specific Subsystems. This results in a difficult maintenance process for this subsystem because, if the development team wants to make a change, then it will affect many other parts of the architecture. Graphics

The Graphics subsystem renders the animations of the game, and handles graphical processes of the software, such as particles, meshes, special effects, shadow and lighting. Graphics depends on Controller because the input manager is called when new resolution settings are applied. It depends on Audio because sound effects are mapped to specific graphics properties.

An unexpected dependency we found was Graphics depending on Physics.

This is because, when they render a post-processed scene, the code would call for the world's physics directly instead of calling for the game state from Game Specific Subsystems and retrieving physics information from that. Controller

The Controller subsystem handles user inputs with two different manager codes: input and device manager. It also holds information about different types of hardware that could be used to play the game, such as normal keyboards, gamepads, and even wiimotes.

An unexpected dependency we found was Controller depending on Graphics. This is because when a user supply inputs for camera control, Controller is required to call functions inside Graphics, such as getLinearVelocity and applyMouseMovement, to complete the requested camera command. Another example is, while using Irrlicht, the printScreen button would call for requestScreenshot command inside Irr_driver code file, which belongs inside Graphics, to take a screenshot. Physics The Physics subsystem deals with all the physics calculations and properties of a dynamic game object. It receives information about the game state, and changes it based upon the information it has on how all the various game entities should interact. Physics depends on four other subsystems: Game Specific Subsystems, Libraries, Core Systems, and Graphics. Physics needs to receive information about the game's state from Game Specific Subsystems. It also needs to communicate with bullet (SuperTuxKart ’s physics engine) which is in Libraries.

An unexpected dependency that was found was Physics depending on Graphics. The reason for this is that within the physics source files they would

sometimes check the animation type of a kart in order to set its physics properties. For example, if the animation type of the kart is a flattened kart, they slow the kart’s speed. Audio

The Audio subsystem handles the overall execution of audio content, handling the triggering of sound effects and background music and the coordination between both. Audio, as expected, contains the audio directory, and depends on the Game Specific Subsystems for information as to the status of the game’s current state; if an event happens that requires a change of music, such as starting a race on a new track, then the Audio subsystem will step in and make it happen. Audio also depends on Core Systems for debugging and error handling, and is depended upon in turn by the Libraries system due to the presence of third party graphics engines (irrlict and bullet).

There were no unexpected dependencies as far as Audio depending on

another subsystem is concerned, but other subsystems depending on Audio is a different story; both Game Specific Subsystems and Graphics call Audio for the execution of sound effects, among other things, which is easily rationalized. We assumed all coordination between audio and other content would be routed through Game Specific Subsystems, but sometimes a subsystem bypasses the “middleman”. Core Systems

Core Systems is responsible for foundational operations that are used by many other subsystems, such as obtaining and processing input, and managing debugging of the system. It contains the utils, guiengine, and io source directories. In our conceptual architecture it is dependent on Network, Game Specific Subsystems, Physics, Graphics, Audio, and Controler.

Using Understand we delved deeper into this subsystem, and obtained the figures below showing how Core Systems’s source directories interact with the other subsystems, and how the source directories interact with each other. As you can see in the Full View, io is mainly depended on by other subsystems, whereas guiengine and utils are mainly coupled to other systems via two-way connections. This makes sense, because guiengine is an interactive subsystem and therefore would require two-way dependencies. Similarly with utils, processes like debugging and logging require two-way dependencies. For example, Game Specific Subsystems is dependent on utils because it needs to write to the logs in utils, and Utils is dependent on Game Specific Subsystems in order to retrieve aspects of the game state when an error is encountered.

The only unexpected dependency is between Core Systems and Libraries. The reason for this dependency is utils/translation.hpp calling tinygettest::Language::from_name().get_name(). This is to get the language from Libraries, which stores that information.

Core Systems Full View

Core Systems Internal View

Network

The Network subsystem is responsible for controlling SuperTuxKart ’s online processes, such as downloading new addons and updating a player’s highscore on SuperTuxKart ’s server. It contains the online and addons source directories. Our conceptual understanding of Network was that it would only need to depend on Game Specific Subsystems and Libraries because it only needs to retrieve the highscores for races in order to update SuperTuxKart’s online servers, and to access various third-party assets. In our concrete architecture, however, we found that Network additionally depends on Graphics and Core Subsystems.

One example of a dependency from Network to Graphics is in the zip.cpp file: there is an include for graphics/irr_driver.hpp which invokes getfilesystem(). This makes intuitive sense. In order for the addon to be merged with the correct files, addons would have to access the file system to determine where to place the newly

downloaded files. An example of a dependency between Network and Core Systems is that addons/addon.hpp incluedes io/file_manager and invokes getAddonsDir() in the addon.cpp -> isAddon() function. This function serves to check if the supplied id is a an addon. Libraries

The Libraries subsystem contains all of the 3rd party SDK’s that SuperTuxKart uses. Every subsystem depends on it because all the subsystems need access to different engines (OpenGL, bullet, irrlicht etc.). However, it depends on Core Systems because some libraries needs to access the games’s file manager. It also depends on Graphics because some of the libraries use attributes that are within the Graphics subsystem. Sequence Diagrams

The sequence diagram above shows how the game handles a user's kart colliding with a powerup. First, the Controller subsystem reads the input the user supplies, and then notifies Game Specific Subsystems that the kart needs to move. Next, the Game Specific Subsystems ask Physics if a collision has happened between the kart and another object. Physics returns true in this case, and provides the id of the object the kart has collided with. Furthermore, Game Specific Subsystems tells Graphics to draw the powerup on the user's screen, and tells Audio to play the sound associated with picking up a powerup. The Graphics subsystem gets the correct OpenGL texture from Libraries, and Audio gets the correct sound file from Core Systems. Lastly the power up is displayed on the screen concurrently with the audio being played.

The sequence diagram above show one kart colliding with another.

First, Game Specific Subsystems calls update() on Physics, and Physics calls getAndMapAction() from Core Systems. This data is used to update Controller, which in turn updates the action in Game Specific Subsystems/Kart and returns control to Physics. Physics then calculates the outcome for the timestamp and detects a collision between two karts. It then calls Graphics to render the collision, which calls Audio to play the sound. Both return to Core Systems on different threads to play the collision sound and show the updated display, and this information is sent to the user through the system’s devices. Concurrency

In SuperTuxKart, multiple instances of concurrency exist throughout the game and must be properly managed at runtime for a satisfactory experience.

SuperTuxKart supports multi-threading, so audio and graphics must run in the

same thread. If the audio and graphics are de-synced, the resulting gameplay would not make sense to the user.

The game supports up to four players at once for local multiplayer, meaning

the game must manage multiple input streams for different input devices. As an open source game, SuperTuxKart offers many different platform and input options, which, on top of the complication of additional client support, require multiple different and concurrent inputs.

Since there are multiple entities in a race, all karts must be managed and

updated concurrently. As karts move through the track, there are frequent position changes, item activations, and interactions between karts. The game must manage

these interactions concurrently in the game state, which is an important part of a high quality game. Division of Responsibilities and Development Team Issues

The three main roles of the development team are:

- Joerg Henrichs (“Hiker”), the Project Leader - Marianne Gagnon (“Auria”), the Main Developer - Jean-Manuel Clemençon (“Samuncle”), the Lead Artist

Since SuperTuxKart is an open source project, throughout development many

people have been able to contribute to the game.

The open source nature also created some issues surrounding SuperTuxKart ’s creation. Since the game's initial release in 2004, the people in each of the three main project roles have changed numerous times, making it hard to transfer information about the game between old and new project leads. This also makes it hard for developers to communicate with one another, as anyone can jump in and contribute at a moment’s notice.

Lessons Learned

Once we got a good grasp of the basic functionality of Understand, the project started coming together much more easily. Though not perfect by any means, the program provided us with all the tools we needed to investigate and formulate our concrete architecture.

Tracing dependencies back to their sources was a very illuminating exercise. It enabled us to gain a level of knowledge of the inner workings of SuperTuxKart that had previously eluded us. It's this knowledge that will be an invaluable asset in the next assignment, when we have to create our own components and dependencies.

Finally, in addition to Understand, we utilized some new software that allowed us to create and share diagrams amongst our group members, akin to the online presentation and document software we use for our presentations and reports. This meant that the creation of our diagrams was more of a collaborative effort, as we could add or suggest changes on the fly. Conclusion

From start to finish, we made quite a few revisions and additions to our ongoing analysis of SuperTuxKart 's architecture.

Our original conceptual architecture was heavily altered to fit a new level of knowledge, and, with the invaluable help of Understand, we arrived at a concrete architecture that (eventually) reflected what we felt was an accurate view of the game's interconnectivity. We were then able to compare both conceptual and concrete to pinpoint exactly where our hypotheses converged and diverged with reality.

Evaluating these comparisons gave us a deeper understanding of both the nature of SuperTuxKart 's development and the development team themselves, especially when we arrived at a dependency we didn't expect. Cohesion within the concrete architecture was at a premium, while high levels of coupling provides a nearly-complete graph of dependencies.

Finally, we updated our sequence diagrams and re-evaluated our understanding of the effects of concurrency and team issues on SuperTuxKart , as well as engaging in a little self-reflection. The deeper analyses we performed on a select few subsystems will play a significant role in the near future, when we shift gears from contemplation to continuation in Assignment 3. References S. (2012). Supertuxkart/stk-code. Retrieved November 9, 2016, from https://github.com/supertuxkart/stk-code Coding Style. (2016). Retrieved November 9, 2016, from https://supertuxkart.net/Coding_Style Overview Architecture. (2016). Retrieved November 10, 2016, from http://supertuxkart.sourceforge.net/doxygen/?title=doxygen