Version: 2.0
CS 4500, University of Utah, Spring 2008
This document outlines the various components, component relations and interfaces of the Sonic Boxmo project.
This SDS will be updated to reflect any design changes.
Team Foo Sharks will create a puzzle game entitled Sonic Boxmo. It will consist of novel and innovative features including a multi-cursor multi-player user interface and fast-paced music based puzzles, which will immerse the players into a unique musical environment. Each player in the game is going to have their own cursor and speaker, and will play in a shared 3D hardware-accelerated environment.
- HID: Human Interface Device
- OpenAL: Open Audio Library
- OpenGL: Open Graphics Library
- SRS: Software Requirements Specification
OpenGL Primer, 3rd Edition - Angel, Edward
Software Project Survival Guide - Steve McConnell
2.1 Overview of modules / components
This project will be broken into 3 primary functional subsystems:
- Graphics
- Manages graphics resources
- handle 'pick' operations
- Sound
- Manages audio resources
- provides a functional base for other components to play sounds in a simple manner
- User Input
- gathers and maintains state of input devices
- abstraction for mouse and Wii Remote hardware to be accessed via the same interface
The game itself will be be built on top of this framework and will include the following components:
- Player
- holds player info (name, score, etc)
- holds player-specific input data (cursor position, button states, etc)
- maps hardware input events to player actions (static)
- manages player-specific graphics elements (cursor, icons, etc)
- holds chain of notes (completed puzzle elements)
- MusicTrack
- holds/manages/outputs information about the current music track such as event timing, sound samples, etc
- MusicBar
- creates a bar which will show information about the current song (similar to the guitar-hero fret-board thing)
- puzzle field
- holds puzzle elements and handles puzzle-rules
2.2 Structure and relationships
The 3 primary functional subsystems above will be entirely orthogonal and have no dependence or use of the other components.
The game-play components will be organized as follows:
- BoxmoMain
- PuzzleField
- Players(1-4)
- MusicBar
- MusicTrack
A primary Game component will contain, initialize, manage, and clean-up all gameplay related components.
A Menu object will manage all functions related to the options menu and will be responsible for instantiation of the Game object.
2.3 User interface issues
The Main Menu will be a simple hierarchical menu with game settings, etc.
The main game interface will be appear as follows:
3.1 Component template description
Identification The unique name for the component and the location of the component in the system. Type A module, a subprogram, a data file, a control procedure, a class, etc Purpose Overview of the top-level requirements of the component... i.e. what is it for and why is it needed. Depends On All components used by this this component and a desription of the reuirement detailing lifespan, scope, etc. Required By List of all components which depend on this component and a description of the requirement (lifespan, scope, etc) Data List of all member variable or other data, their scope and types and a description of what they hold including format information
Organized as folows:
- Name (type, scope): description
Functions A list of all functions and interfaces, their parameters and return values and what they do
Organize as follows:
- Function Name
- params (list of parameters)
- return (returned data)
- description of function
Resources A complete description of all resources (hardware or software) external to the component but required to carry out its functions. Some examples are CPU execution time, memory (primary, secondary, or archival), buffers, I/O channels, plotters, printers, math libraries, hardware registers, interrupt structures, and system services. 3.2 GraphicsMain
Identification GraphicsMain Type class Purpose Manages all top-level graphics needs:
Draw the scene, create frame-bufferDepends On DrawableObject: Used only when drawing the scene. Does not control instantiation or removal
Required By Main: There will be a single instance of this object (enforced) which will be accessible through a global pointer. main has total lifetime control Data
- screenW (int, protected): Width of teh screen in pixels
- screenH (int, protected): height of the screen in pixels
- screenBPP (int, protected): bits-per-pixel of teh screen (screen pixel format) (16 or 32)
- windowCaption (string, public): caption of the main window
- fullScreen (bool, protected): full screen or windowed mode
Functions
- drawScene:
- params (none)
- return (none)
- draws all objects in the current scene (DrawableObject::SceneList), swaps the fram buffer and returns
- constructor
- params (int W, int H, int BPP, string WindowCaption, bool FullScreen)
- Inits all member vars to params, creates the display windows and frame buffer, init all OpenGL and GLUT states then returns
- destructor
- purge Materials and AudioSamples
Resources Graphics Memory for frame buffer 3.3 DrawableObject
Identification DrawableObject Type class Purpose Basic Drawable Object, stores geometry data and a pointer to a Material object and handles drawing operations Depends On materialFile: used to store and setup texture/material resources for the object Required By GraphicsMain, others (all game objects with visual components) Data
- SceneList (DrawableObject*, public (static)): pointer to the start of the scene linked list
- geoType (int, public): specifies the type of geometry, maps to OpenGL types (points = 0, lines = 1, triangles = 2, quads = 3)
- points (vector<vector<float>>, public): vector with all verteces in the geometry, orderd as follows:
each row has 8 entries {x,y,z,r,g,b,tx,ty} (x,y,z coords, rgb color info and texture-x and texture-y, row count must be appropriate for the specified geoType)- rot (vector<float>): rotation information
- pos (vector<float>): position information
- materialFile (string, public): relative path to the material file to use
- hidden (bool, public): if true object is not drawn
- previousObject (DrawableObject*, public): pointer to previous object in the scene, NULL for furst object in scene
- nextObject (DrawableObject*, public): opinter to next object in scene, NULL if last object
Functions
- constructor
- params (none)
- Inserts self into head of SceneList, sets hidden to true, sets textureFile to null and geotype to 0
- destructor (virtual)
- removes self from SceneList and links previous node to next node
- Draw (virtual)
- params (none)
- return (none)
- sets appropriate GL state, calls Material::applyMaterial for materialFile and then draws all verts in points, revert GL state and returns
Resources memory for points vector
3.4 Material
Identification Material Type class Purpose Store texture data and other material settings (lighting interations, etc) Depends On none Required By DrawableObject Data
- MatList (map<string, Material*>, static ): map of all loaded materials, indexed by the relative path of the material file
- Palette (map<int, string>, static): maps palette index to a material file
- TextureImage (GLuint[3], private): actual pixel data for the material texture
- BumpMap (GLuint[3], private): pixel data for bump map
- MaterialFile (string, private): relative fie path to the material file, used for identification to prevent loading the same material multiple times
BMP texture files
Palette files... format outlined in 7.2Functions
- ApplyMaterial (static)
- params (string MaterialFile)
- return (bool success)
- will check the MatList to see if the material is loaded, if it is, the texture/bump maps are applied for the material, if not, a new material is created
- PurgeMaterials (static)
- params(none)
- return (none)
- Deallocate all loaded materials
- constructor
- params (string MaterialFile)
- loads the material file, generates textures/bumpmaps and insters pointer to self in MatList map
- destructor
- deallocates texture and bump map data and removes self from MatList map
Resources Memory space for texture and bump maps. 3.5 AudioSample
Identification AudioSample Type class Purpose store and playback sounds Depends On BASS audio library Required By Data
- Clips (map<string, AudioSample*>, static): map to all loaded samples, indexed by relative path to audio file
- AudioData (Channel, private): BASS library channel... stores audio data
WAV or MP3 audio data files
Functions
- PlayClip (static)
- params (string SampleFile, vector<int> levels)
- return (none)
- checks the Clips map to see if the sample is loaded and loads creates a new AudioSample for the file if it is not
plays the sample with the supplied output levels- PurgeClips (static)
- params(none)
- return (none)
- Deallocate all loaded samples
- contructor
- params (string SampleFile)
- load the sample file into AudioData, add self to Clips map
- destructor
- deallocate AudioData and remove self from Clips
Resources Main memory for audio data
exclusive control of sound hardware for buffered audio playback3.6 BoxmoMain
Identification BoxmoMain Type class Purpose main game class, has the main game loop... process game rules, start and stop the game as needed, etc. Depends On Everything Else Required By Main Data
- Players (vector<Player*>, protected): all players in the game (human players)
- MB (MusicBar, protected): MusicBar instance
- Puzzle (PuzzleField, protected): puzzleField instance
- deltaT(double, protected) time between calls of GameLoop
Functions
- Constructor
- params (none)
- init everything to 0 or NULL
- StartGame
- params (none)
- return (none)
- load options file, set game settings accordingly, allocate game objects and start the game
- DoInput
- params (none)
- return (none)
- checks the state of all input devices which have mapped functionality and alter game object states accordingly
- GameLoop
- params (none)
- return (none)
- update deltaT and call Update on Player, SB, and Puzzle
Resources A complete description of all resources (hardware or software) external to the component but required to carry out its functions. Some examples are CPU execution time, memory (primary, secondary, or archival), buffers, I/O channels, plotters, printers, math libraries, hardware registers, interrupt structures, and system services. 3.7 PuzzleField
Identification PuzzleField Type class Purpose manage the puzzle elements, award points as objectives are completed, etc. Depends On PuzzleElement Required By BoxmoMain Data
- Elements (vector<vector<PuzzleElement*>>, protected): all of the elements in the puzzle
- Groups (vector<vector<int>>, protected): arrays of indeces into Elements for every group ID
- Width (int, protected): number of elements wide
- Height (int, protected): number of elements high
- numColors(int, public): number of valid colors
Functions
- constructor
- params (int W, int H)
- populate Elements vector and set an initial random state for the puzzle
- RotateEements
- params (int groupID,int direction, Player* generatingPlayer)
- return (none)
- the GroupID is the ObjectName used to the gl selection which coresponds to a triad of puzzle elements... get all puzzle elements in the group, sets Moving to true and sets their dest(x,y,z) to the new position and vel(x,y,z) to dest(x,y,z)-(x,y,z)*(2 or [1/desired travel time]). Swaps their entries in the Elements vector to the correct spot. Sets ActivePlayer of the elements to generatingPlayer
- Update
- params (double deltaT)
- return (none)
- for each PuzzleElement E in Elements call update
- CheckMatch
- params (int groupID, Player* activePlayer)
- return (none)
- check if all of the elements in the group are the same color and not moving, if they are call activePlayer->addNote(color) and then call Explode() for all elements in the group
Resources memory for Elements vector 3.8 PuzzleElement
Identification PuzzleElement Type class, extends DrawableObject Purpose store player information, cursor for player and handle input mapping Depends On DrawableObject, Material Required By PuzzleField Data
- Moving (bool, public): is this moving (animated)? i.e. locked for other actions
- dest (vector<float>, public): for animation... target point(x,y,x)
- vel (vector<float>, public): for animation, x,y,z velocity... only used if moving is true
- color (int, public): what color is the piece? maps to pallet
- groups (vector<int>, public): list of all groupIDs to which this element belongs
- SampleFile (string, pubic): sample file for the element
- Player* activePlayer
- PuzzleField* myField
Model file format defined in section 7.3 of this document
Functions
- constructor
- params(float x, float y, string ModelFile, int color, string SampleFileName)
- load model from file, set materialFile from Material::Palette[color], set SampleFile to SampleFileName
- Update (virtual)
- params (float deltaT)
- return (none)
- if Moving == true: if(distance from (x,y,z) to dest(x,y,z) < mag(deltaT*E.vel) then (x,y,z) = dest(x,y,z) and call myField->checkMatch for each group to which E belongs... else offset pos.(x,y,z) by deltaT*vel
- Explode
- params (none)
- retrun (none)do some animations then change to a new random color between 0 and myField->numColors
Resources 3.9 Player
Identification Player Type class Purpose store player information, cursor (position and image) for player and handle input mapping Depends On none Required By BoxmoMain, PuzzleField, PuzzleElement Data
- Name (string, protected) : player name
- Score (int, protected): game score
- noteChain (vector<PuzzleElement>, protected): notes in note chain
- cursor (drawableObject, protected)
- myInput (InputDevice, protected)
Functions
- pollDevice
- params (none)
- return (none)
- get input state from mapped device and set cursorposition accordingly
Resources input devices 3.10 MusicBar
Identification MusicBar Type class (extends DrawableObject) Purpose draw the scrolling music bar from data provided by the music track Depends On MusicTrack (song data)
DrawableObject (inherited)Required By BoxmoMain Data
- myTrack (MusicTrack*, protected): pointer to the music track for the puzzle
Functions
- Update
- params (float deltaT)
- return (none)
- advance the position of the bar to current song position using deltaT
- Draw (over ridden from DrawableObject)
- params (none)
- returns (none)
- draw the music bar and all of the notes in the active section of the song in time-order
Resources 3.11 MusicTrack
Identification MusicTrack Type class Purpose Store timed song information, provide accuracy feedback on player-generated notes Depends On AudioSample Required By MusicBar Data
- SongFile (string, protected): the path to a song file
- BPM (int, protected): beats per minute
- MeasureSize (int, protected): size of the measure
- NoteBeatNumbers (vector<int>, protected): beat numbers for all notes in the song
- NoteSamples (vector<string>, protected): sample files for all notes in the song (same indexing as NoteBeatNumbers)
- NoteColors (vector<int>, protected): note color for all notes in the song... (same indexing as NoteBeatNumbers)
- songPosition (float, protected): the current position of the song
Song File format outlined in Apendix 7.1
Functions
- Update
- params (deltaT)
- returns (none)
- store songPosition in a local (lPos) increment songPosition by deltaT and then play all notes whose NoteBeatNumber lies between lPos and and songPosition. This shoud work even with this function only being called once per frame as the frame rate should be high enough to allow proper timing.
Resources memory space for arrays
sound hardware for multiple samples
3.12 MainMenu
(TBA)
Being a new development, reuse in Sonic Boxmo is limited to using existing libraries and API's such as the BASS Audio Library, OpenGL, RawInput, and Wiimote-API and the C++ standar template library.
It was initially intended to use the OpenAL audio library but it does not support explicit channel output on 5.1 or 7.1 speaker systems. The change to the BASS audio library means that we are using a closed source license-restricted library (free for non-comercial use). We may need to rework our design if we find an open library to do what we need.
7.1 Song File format
song files will be formatted as follows:
Header:
Name=Song Name
BPM=[int] //beats per minute
MeasureSize=[int] //size of each measureBody(notes)
each line of the body will provide info for a single note in the song:
BeatNumber:Sample File Path:Volume Level:Color //types are:
BeatNumber = int... number of beat in the song (ints only... if you need off beats double BPM and all BeatNumbers.. you get it.. good job)
SampleFile = string... relative path to the sample file
Color = int... index into color pallet, -1 specifies a note in the background music and it will be ignored by the puzzle