SENG201 Software Engineering I - Project: Resource Stockpiling
SENG201 – Software Engineering I Project Specification Resource Stockpiling
1 Introduction
1.1 Administration
This project is a part of the SENG201 assessment process. It is worth 30% of the final grade, and it is capped up to 100 marks (i.e., the total marks for it can’t exceed 100). This project will be done in pairs (i.e., teams of two students). You must find your own partner and register the team on LEARN. Submissions from individuals will not be accepted. Pairs are not allowed to collaborate with other pairs, and you may not use material from other sources without appropriate attribution.
Plagiarism detection systems will be used on your report and over your code, so do not copy the work of others. Plagiarised projects will be referred to the University proctor for disciplinary actions. Your deliverables must be submitted on LEARN. Students will be asked to demo their project during lab and lecture times.
Actual dates and times are detailed in Section 6.3. The drop dead policy and other penalties are detailed in Section 6.4.
You can find all the project-related information and resources in the “Project” section on LEARN.
1
1.2 Outline
This project will give you an idea of how a software engineer would create a complete application (featuring a graphical user interface) from scratch.
In this project you will build a game in which you buy and maintain a set of resource towers. You will be able to purchase towers of different types; buy upgrades and items to improve the towers; select a number of rounds with particular difficulties to play; and fill up carts with materials from your towers in a round to earn money/points. You will continue to play and successfully fill up all the carts in the rounds with the goal of earning money/points and improving your towers.
The idea of the game is slightly open to allow some room for creativity, but ensure you implement the main project requirements, as that is what will be graded.
We encourage you to think of the assignment as a project rather than a pro- gramming assignment. Programming assignments often have a clearly defined specification that you can follow step-by-step. However, in practice, software engineering projects require a lot of thinking from the engineers to find out what exactly to build, why, for whom, and how. Therefore, specifications and requirements are often vague and need to be clarified during development.
1.3 Project Management
Adequate planning will help you minimize risks that can negatively impact your project (e.g., falling behind or poor testing). Defining time estimates, clear goals, and realistic milestones will give you a much higher chance of success.
To help you with this, you must record the following data weekly:
-
Hours you spent working on the project during the week.
-
Activities you carried out during the week.
-
If you achieved the goals planned for the week or not.
-
The risks you identified or faced during the week.
-
How satisfied you are with your and your partner’s contribution to the
project during the week.
A quiz to record this data is available on LEARN.
You will earn marks by entering the data on time. Similarly, you will lose marks if you fail to regularly record the data, see Section 6.4 for more details.
1.4 Help
This project can get confusing and frustrating at times when your code does not work. This will likely be the largest program you have written thus far, so
2
it is very important to break larger tasks into small achievable parts and then implement these at a time, testing as you go.
Having a nice tight modular application will help with debugging, so having appropriate classes is a must. If you are having problems, try not to get too much help from your classmates and instead ask for help from your tutors. You can email them or ask them questions in labs. Always save your work and have backups. You will be using the university’s GitLab1, eng-git, for a Version Control System (VCS). Ensure you commit regularly and add detailed messages. For more information about Git see Tutorial 1 and its extension.
2 Requirements
This section describes what your game must do and is written as a set of re- quirements. At the beginning of your project and to get started, try thinking of each requirement as a separate ticket that needs to be closed before others are started, it will help you have code that works and can be built upon, instead of a lot of broken spaghetti code.
Hint: Functionality can be placed in its own package or class. Modularisa- tion is the key, especially when you begin GUI programming.
2.1 Setting Up the Game
When your game first starts, it should ask the player to:
-
Choose a name. The length must be between 3 and 15 characters and must not include special characters.
-
Select the number of rounds they would like to play (between 5 and 15 rounds).
-
Choose a difficulty
-
(a) There must be at least 2 options.
-
(b) This should scale how difficult the game is in a noticeable way. (For example, how much money the player starts with, money earned, and/or what shows up in the shop; this is up to you).
-
(c) You may want the harder difficulties to give more points for the same action.
-
-
Pick three starting towers from a selection. A tower should have at least the following stats:
-
(a) Resource amount: The amount of resources to load into carts per action.
-
(b) Reload speed: The time between resource loading actions.
-
1 https://eng- git.canterbury.ac.nz/
3
(c) Resource type: For example, water, food, building materials, . . . get creative!
-
(d) Level: After some number of points/upgrades, the tower should “level up” and improve its stats in some way.
-
(e) Cost: When buying from (and selling) to the shop. Note that the sale price can be a reduced amount of the buying price.
5. (Optionally) Be able to name the towers. 6. Start the first round.
2.2 Playing the Main Game
Once the player has finished the setup and selected their towers, the main game can begin. The game is played in rounds, where up to 5 of the player’s towers must fill all the carts in a round. To successfully complete a round the player must fill up all the carts before any of them go the full track distance without being filled.
When you successfully fill all the carts, you have won the round and will receive points. The points can be used to buy items or upgrades to improve your towers. The amount of points received when the player wins is up to you (and may be scaled with difficulty).
The following options will be displayed to the player:
-
View the amount of money you have, the current round, and the number of rounds remaining.
-
Go to the shop and buy new towers or items to upgrade towers and sell those from their inventory back.
-
There should be 3 to 5 different towers the player can buy
-
The towers sold may depend on other factors (e.g., a rarity system could be used, with rarer towers becoming more common [or being unlocked] in later rounds).
-
There should be 3 or more different items to buy (a shop may have more than 1 of the same item)
-
Item functionality may include (but is not limited to): (a) Improving one or more tower stats
(b) Increase tower XP (or level)
(c) Changing tower type
-
-
Go to the inventory and:
(a) View the player inventory and the current items they have. The inventory includes:
i. Five or fewer main towers (those used in rounds) 4
-
Five or fewer reserve towers (those not used in rounds, much like substitutes in sports)
-
Any number of upgrades
-
(b) Move towers between the main group and the reserve group (the main
group must always have at least one tower)
-
(c) Use an upgrade on any tower
4. Play a round. Within each round, you need to use your towers to fill up a number of carts. Each of these is discussed in more detail below:
-
(a) Each round, the player can choose a difficulty which shall be based off one or more of:
-
Distance of track (i.e., in meters or kilometers)
-
Information about the carts to fill:
• Number of carts • Size of carts
• Type of carts -
(Optionally) Different ’map’ modifiers. (For example an easy round may boost all towers’ reload speed)
-
-
(b) Carts
-
A round is made up of a number of carts which need to be filled depending on difficulty (loosely 3-10).
-
Carts have the following stats:
-
Size: Amount of resources to be filled with
-
Resource Type: Type of resource which can fill it (same as
the possible tower types), though you may also wish to have
a basic type that can be filled with any resource
-
Speed: in meters per second or kilometers per second. This value is used to determine how long a cart will be on the track where it can be filled by the player’s towers. For example, a cart moving at 10m/s will complete a 100m track in 10
seconds.
-
-
A round has some number of carts (above) that have to travel a predetermined track distance. A round is considered complete only if all carts are filled completely within that distance.
-
Towers, in their simplest form, fill all carts on the tack at the same time (as long as the cart typing allows it to be filled by the tower’s type).
-
The difficulty of rounds should be impacted by the chosen game difficulty and round number (i.e., later rounds should be harder).
5
-
(c) Rounds
2.3
5.
6.
-
Each ‘round’ the player should be able to select between 3 differ- ent options for the upcoming round, based on some information. Such differences may be down to slight randomization in the stats, number of carts to be filled, length of the track, etc.
-
Winning a round should give the player money to spend at the shop (based on the relative difficulty) and optionally some form of points (though this may be tied to the money earned).
After a round:
(a) All towers/items in the shop are updated/refreshed. (b) All rounds are updated.
(c) Random events have a chance of occurring as detailed below.
There will also be some random events you will need to implement. These will only happen after a round. The chances of these events occurring may depend on the difficulty setting but should be high enough that a few will likely occur over a game. The player must be alerted when any of these random events occur:
-
(a) A tower has one or more of its stats (including XP) increased or decreased.
-
(b) A tower breaks.
-
A broken tower can either:
A. Be removed from the player’s inventory entirely, or
B. Be placed in a broken state and require a specific item to berepaired to working order
-
The chance should increase if the tower was used in the previous
round
-
Finishing the Game
The game ends when one of the following occurs:
-
All rounds have passed and been successfully completed, therefore the player has won.
-
The player does not have any working towers or money to buy more, then, the player loses.
-
The player has covered the maximum allowed distance in a round but has not filled all the carts, and the player loses. (Optionally) You may wish to include an XP value for the player that allows them to lose a number of rounds before they lose the whole game.
Upon ending, a screen will display the user’s name, a message about whether they won or lost, the selected number of rounds they initially chose, how many rounds they completed, the amount of money gained, and the amount of points gained (or some other score value).
2.4 Extra Credit Tasks
If you have finished early and have a good-looking application, then you will be in for a very high mark. If you want to do more, please discuss it with the tutors in the lab. You are free to add any features you wish; just be careful not to break anything. Here are some ideas, and you do NOT need to implement them all to get full marks:
3
You may want rounds to have an emphasis on specific types and allow players to change their main party when selecting a round to deal with them.
You may want to introduce random events during the round that could include an ability that disables a tower for a short time or increases the reload speed.
You may want to introduce new tower types with special characteristics, for example, support towers that do not provide any resources but instead buff other towers.
You may want to show the game in real-time with animations.
You may want to allow the player to save the current state of the game and be able to load it up at a later time.
You may want to add a storyline to your game, including consistent char- acters and a plot that gets told through pop-ups or dialogue.
You may want to add some artwork.
You may want to include some music or sound effects. We recommend you use resources such as pixabay.com or freesound.org for free-to-use images and sound. It is your responsibility to adhere to any licensing terms and these should be referenced in your README.
Design and Architecture
This section provides some ideas on how your program should be structured. The following are some class candidates who should be represented in your pro- gram. Important things to think about here are interactions between classes, what classes should be instantiated, how you could use interfaces and/or inher- itance, and how you could apply the design patterns you’ve learned and will learn in SENG201.
3.1 Towers
There shall be different towers. Three will be enough. Each tower has at least a resource amount, reloading speed, resource type, level, and cost.
7
3.2 Carts
There shall be different carts. Between three and ten per round. Each cart has at least a size, resource type, and speed.
3.3 Rounds
There shall be multiple rounds per game. Between five and fifteen per game. Each round has a difficulty that is determined by a combination of the distance allowed, the number of carts to fill, and the size of the carts to fill. This difficulty should be selected each round.
3.4 Items
There shall be different types of items (e.g., towers, upgrades). You can have up to five main towers, five reserve towers, and as many upgrades as you like. Each item will have a cost and upgrades should provide some measurable im- provement.
3.5 Purchasable
Both towers and items can be bought from the shop and should be displayed in the inventory. These both require a buying price, a sell-back price, and a description.
3.6 Service Classes
Instead of storing all the game logic within the GUI controller classes, it is beneficial to abstract the functionality out to other classes, often called ‘service’ classes. Doing so promotes code reusability and testability. Service classes you implement may encapsulate a collection of related logic from the domain, such as a MarketService.
3.7 Game Environment
The game environment contains much of the overarching logic for your game, will implement functions to provide the options mentioned above, and will call methods of the above classes to make those options happen. The game environ- ment keeps track of the game state.
Try to keep your code modular and avoid putting user interface (UI) code in your game environment or domain classes. Separating the game logic from the UI code will make developing and maintaining the application easier.
8
4 Assignment Tasks 4.1 Sketching UML
Before you start writing code, sketch out a UML use case diagram detailing the program’s users (actors) and their interactions with the system (use cases). This diagram will help you to identify the main functionalities of the program and to visualize its scope.
In addition to this diagram, create a UML class diagram of how you think your program will look like. It will help you get an idea of what classes there are and what class attributes are required, and it will get you thinking of what classes communicate with other classes (call methods of another class).
4.2 Implementing a Graphical Application
You will implement a graphical application for your game using JavaFX, which will be explained in labs. For this assignment, we do not recommend writing the FXML code by hand. Instead, use the Scene Builder application (optionally within the IntelliJ IDE). This lets you build graphical interfaces in JavaFX by dragging and dropping components onto a canvas onscreen. It will automatically generate the FXML code to create the graphical interface you built, which you can then pair with a controller class.
Please note that you are required to ensure that any automatically generated code complies with the rest of your code style, so you will need to change variable/method names and code layout.
Once you have built your interface, the next task is to wire up the graphical components to the methods, and to update the onscreen text fields with the new values of your class attributes/member variables. Most of these functions are triggered by “Setting up the Game” first to get used to GUI programming. You might need to adjust your methods to achieve this slightly. Then, move on to the main game.
Note that this is the largest task to complete, and many students underes- timate how much time it will take. Try to be at this stage one week after the term break if possible.
4.3 Writing Javadoc
Throughout your application, you need to document what you implement. Each class attribute should have a Javadoc explaining its purpose. Each method needs to explain what it does, what variables it takes as parameters, what types those variables are, and what the method returns (provided it does not return void). You should build your Javadoc regularly, as it integrates into the IDE very nicely and will aid you in writing good code.
9
4.4 Writing Unit Tests
You should design JUnit tests for your smaller, basic classes, such as Tower, Cart, Store, and their descendants, if necessary. Try to design useful tests, not just ones that mindlessly verify that getters and setters are working as intended. Writing good unit tests with JavaFX also requires good abstraction of domain logic to external classes such as a ‘service’ layer, which means you can test functionality independently of the GUI itself.
4.5 Report
Write a short two-page report describing your work. Include on the first page:
-
Student names and ID numbers.
-
The structure of your application and any design decisions you had to make. We are particularly interested in communication between classes and how interfaces and/or inheritance were used. You might want to reference your UML class diagram.
-
An explanation of unit test coverage and why you got a high/low percent- age coverage.
Include on the second page:
-
Your thoughts and feedback on the project.
-
A brief retrospective of what went well, what did not go well, and what improvements you could make for your next project.
-
The effort spent (in hours) on the project per student.
-
A statement of agreed percentage contribution from both partners.
4.6 A note on effort distribution
The “typical” or “common” distribution of the overall effort spent on these activities is: around 5% creating the UML diagrams; development of the graph- ical application is the most time-consuming task, taking around 60% of your time; documenting your code writing the report would take the last 5%.
However, note that these numbers vary between students, and these percent- ages are not supposed to be the exact amount of effort invested in each task. They are only a rough guideline (e.g. we would not expect you to spend 50% of your time on creating UML diagrams or writing the report; on the other hand, we would expect that implementing the graphical user interface takes quite a substantial portion of the effort).
10
5 Deliverables
5.1 Submission
-
Please make sure your Eng-Git repository contains the following: • Your source code (including unit tests).
Push the final commit to your Eng-Git repo to the ‘main’ branch before the due date and time mentioned in Section 6.3. Only one member of the team is required to push the final commit.
-
Please create a ZIP archive with the following:
-
UML use case and class diagrams as a PDF or PNG (do not submit Umbrello or Dia files; these will not be marked). These diagrams must be made by you, do not use an automatic tool to generate them. Note: If you use PlantUML you may want to include a file with the code for the diagram as well as the image.
-
Your report as a PDF file (do not submit MS Word or LibreOffice documents; these will not be marked).
-
Submit your ZIP archive to LEARN before the due date mentioned in Section 6.3. Only one member of the team is required to submit the ZIP archive.
5.2 Demos
During the last week of the term, you will be asked to demo your project during lab and lecture time. Each team member must be prepared to discuss any aspect of your application; we will be asking questions about any and all functionality. There will be a form on LEARN in which you can book a time slot. Ensure you are both available, as you must attend the demo as a pair.
Only one member of the team needs to book a slot for the team, but both members are expected to attend the demo at that time; do not double book slots.
-
