Skip to content

Project (🥚 Egg Rally ⚔️)

Logo

Overview

For the Project, you will be making a game called Egg Rally, inspired by the game Vampire Survivors.

Video guide (watch the first 2 minutes and 30 seconds): link

In Egg Rally, you roleplay as an egg in a kitchen, and you have to survive as long as possible against the kitchen's cooking utensils.

The Grading section below will walk you through the finer details and specifications of Egg Rally.

Details

Implementation

You are required to use Pyxel. This project is meant to assess your ability to do game development while using the MVC architecture and adhering to SOLID principles.

You may refer to the following references:

The other lectures may also be helpful.

Submission

The Project will be graded in phases. Your submission will be graded until the highest phase it meets requirements for.

Should you opt to make a submission for phase P, ensure that a branch named phase<P> is present containing your submission, where <P> is two characters long (e.g., phase03, phase11). Only the branch with the highest-numbered phase number will be checked.

Your code in the master branch will not be checked.

Your program should be executable via the following command:

python3 -m egg_rally

In particular, your main Python program should be named egg_rally.py.

Grading

There are several phases (numbered starting from 0). Some phases merit regular points (🔴), while all other phases merit heart points (❤️).

Each phase consists of several subphases, pertaining to different aspects of the game that are involved in that phase.

Some subphases are linked to each other, and this is shown in the format latter subphase « former subphase. This indicates that the former subphase must be accomplished first. If there are conflicting specs between the latter and former subphases, the latter subphase takes precedence.

Note that you are free to implement more than what is being asked for in a subphase, but this will not merit additional points.

The Project will be graded over 100 points.

Warning

Note that features implemented for later phases will not be credited if your submission does not meet requirements for earlier phases.

For example, suppose you implemented a feature meant for Phase 5. If you do not make it to Phase 5 (because, say, you failed to meet all requirements for Phase 3), you will not obtain credit for the feature.

Phase 0 (30 ❤️)

Phase 0 demo

[0a] World

In Egg Rally, there is a concept of a world. This is where the egg and the eggnemies wander around. You must use Pyxel's default black screen for the world in this phase.

In this phase, the world must be constrained to the window size you set your Pyxel game to have.

Note that the world is not required to have obstacles in this phase.

  • A world exists.
  • The world is finite, and is limited to the window provided by Pyxel.
  • The world does not have obstacles.

[0b] Egg

Egg Rally wouldn't be Egg Rally if, well, an egg didn't exist...

For this phase, you must represent the egg as a rectangle.

The egg must be able to move around the world via the following keys:

  • W or Up, to move up,
  • A or Left, to move left,
  • S or Down, to move down, and
  • D or Right, to move right.

In particular, a player must be able to move the egg around just by using the W, A, S, and D keys or just by using the Up, Left, Down, and Right keys.

As the world is finite, the egg must not be able to go out of bounds.

The egg must have an HP stat that is shown in the format (current hp)/(max hp) (e.g., 12/20).

  • An egg exists.
  • The egg is a rectangle.
  • The egg can be moved around.
  • The egg cannot go out of bounds.
  • The egg has an HP stat that is shown in-game.

[0c] Eggnemies

Egg Rally wouldn't be Egg Rally if, well, the egg didn't have anything to rally against...

You will be giving the egg multiple eggnemies to go against. Eggnemies must also be represented as rectangles, and they must be distinguishable from the egg.

For this phase, you only need to support one kind of eggnemy. Eggnemies do not need to have an HP stat, and there must be a fixed number of them in the world at the start of the game.

Eggnemies are still rather dumb in this phase: they just follow you around at a fixed speed. Eggnemies are allowed to completely overlap with each other as they're moving around.

  • Exactly one kind of eggnemy exists.
  • There can be multiple eggnemies in the world.
  • Eggnemies are rectangles, and they are distinguishable from the egg.
  • Eggnemies do not have an explicit HP stat.
  • The initial number of Eggnemies is fixed.
  • Eggnemies just follow the egg around.
  • Eggnemies may completely overlap with each other.

[0d] Damage

For every second the egg is in contact with an eggnemy, it must take 1 damage. The egg can be damaged at most once every second.

Once the egg reaches 0 HP, it must disappear from the world, and all eggnemies must stop moving.

The egg is also allowed to attack eggnemies using the L key. When the egg is close enough to an eggnemy and attacks, the eggnemy is defeated and disappears from the world.

Unlike the egg, eggnemies do not have invincibility frames; i.e., holding the L key must deal continuous damage.

  • The egg takes contact damage.
  • The egg disappears upon reaching 0 HP.
  • All eggnemies stop when the egg disappears.
  • The egg can damage eggnemies.
  • Eggnemies disappear upon being damaged.

[0e] Settings

To help the CS 12 26.1 team check your submissions, you will need to create a settings file that stores various information about the game.

The settings file must be called settings.toml. For this phase, it must contain values for the following entries:

  • the game's FPS,
  • the world's width,
  • the world's height,
  • the egg's initial HP,
  • the egg's width,
  • the egg's height,
  • the number of eggnemies,
  • an eggnemy's width, and
  • an eggnemy's height.

Optionally, you may name the settings file included in the repo example.settings.toml instead (but you must still refer to it as settings.toml in the code), and include settings.toml in your repo's .gitignore.

  • A settings.toml or example.settings.toml file exists, which sets all of the necessary values.

Phase 1 (45 ❤️)

Phase 1 demo

[1a « 0a] World

The world is still finite, but it does not have to be constrained to the Pyxel window. The border of the world should be colored white.

  • The world is finite, but is not limited to the Pyxel window.
  • The world has a white border that can be seen as the egg gets close enough.

[1b « 0b] Egg

The egg must now be at the center of the screen at all times. What is shown on screen must be relative to where the egg currently is.

  • The egg must always be at the center of the screen.

[1c « 0c] Eggnemies

Eggnemies must now have their own HP stats (all eggnemies of the single type must have the same max HP). New eggnemies may now also spawn in the world randomly, both inside and outside the Pyxel window ("on- and off-screen").

For tracking purposes, the number of eggnemies that have been defeated so far should be visible in-game.

  • Each eggnemy must have its own HP stat that is shown in-game.
  • New eggnemies may spawn on-screen and off-screen.
  • The number of defeated eggnemies must be visible in-game.

[1d] Boss

For this phase, there is a boss that must spawn after defeating a certain number of eggnemies.

Like the egg and eggnemies, the boss is represented as a rectangle, and also has its own HP stat. The boss must be distinguishable from the egg and eggnemies.

Like eggnemies, the boss follows the egg around, but at a faster speed.

The egg must take 3 damage every time it comes into contact with the boss. Like eggnemies, the egg can attack the boss and deal damage to it.

  • A boss exists, and it spawns after defeating a certain number of eggnemies.
  • The boss is a rectangle, and it is distinguishable from the egg and eggnemies.
  • The boss has an HP stat that is shown in-game.
  • The boss follows the egg around (faster than eggnemies).
  • The egg takes contact damage from the boss.
  • The egg can damage the boss.

[1e] Progression

There must now be an in-game timer that indicates how much time has passed in the MM:SS format (e.g., 02:30 for 2 minutes and 30 seconds).

Once the boss is defeated:

  • The boss disappears from the game.
  • All entities stop moving.
  • The timer stops.
  • Victory text (e.g., You win!) must appear above the egg.

In other words, the game ends when the boss is defeated.

  • An in-game timer exists, and it only stops once the boss is defeated.
  • The boss disappears once it is defeated.
  • All entities (including the egg) stop moving once the boss is defeated.
  • Victory text appears above the egg once the boss is defeated.

[1f « 0e] Settings

The settings.toml file must have the following additional entries:

  • the screen's width,
  • the screen's height,
  • an eggnemy's initial HP,
  • the number of eggnemies you need to defeat before the boss spawns,
  • the boss' initial HP,
  • the boss' width, and
  • the boss' height.

The entry that previously referred to the number of eggnemies should now refer to the initial number of eggnemies.

  • A settings.toml or example.settings.toml file exists, which sets all of the necessary values.

Phase 2 (45 ❤️ + 15 🔴)

Phase 2 is about refactoring your existing code.

[2a] MVC

Aside from your main egg_rally.py file, your project must now also have model.py, view.py, and controller.py files for the model, view, and controller, respectively.

  • Your code must follow the MVC architecture.

[2b] Tests

You are expected to use Pytest for testing your code. For this phase, you are required to have at least 5 test_* functions across your test_*.py files.

Different test_* files must test meaningfully different aspects of your code.

Your tests will be run using the following command:

pytest

All of the existing tests must pass.

  • Enough tests exist.
  • All tests pass.

Phase 3 (45 ❤️ + 25 🔴)

Phase 3 demo

[3a « 1e] Restart

In Phase 1, everything stops once either the egg or the boss is defeated. Now, once the egg or the boss is defeated, the player must have the option to restart the game via the R key.

After restarting, the game should revert back to its initial state (0 eggnemies defeated, timer set to 00:00, etc.).

Note that restarting should not be possible while the game is still ongoing.

  • Restarting is possible only once the game ends.
  • Restarting resets all game values.

[3b] Leaderboard

For our purposes, a run starts when the game begins and ends when the game is over (i.e., either the egg or the boss is defeated). In particular, consecutive runs are separated by game restarts.

The score of a run is simply the amount of time it takes to defeat the boss, according to your game's timer. The smaller the score is, the better.

The game must now keep track of the top 3 runs in your game, where the top run is the one with the lowest score, the next top run is the one with the next lowest score, and so on.

Note that runs where the egg is defeated should not be included in the leaderboard.

Specifically, the leaderboard must be shown in the following format:

Top 1  AA:BB
    2  CC:DD
    3  EE:FF

If there are less than 3 runs so far, the blank entries in the leaderboard must be represented by --:--.

  • The leaderboard exists.
  • The leaderboard shows the correct information.

[3c « 2b] Tests

For this phase, you are required to have at least 10 test_* functions across your test_*.py files.

Different test_* files must still test meaningfully different aspects of your code.

Of course, all of the existing tests must pass.

  • Enough tests exist.
  • All tests pass.

Phase 4 (45 ❤️ + 35 🔴)

Phase 4 demo

[4a « 1c, 1d] Eggnemies, Boss

Note that in previous phases, eggnemies could completely overlap with each other, as shown in the following image:

Sample of complete overlapping

For this phase, this is no longer the case. Eggnemies and the boss should not completely overlap each other.

We say that an entity (eggnemy or boss) completely overlaps with another entity iff their rectangles have the same center.

Note that partial overlapping is still permitted.

  • Eggnemies and the boss must not completely overlap with each other.

Phase 5 (45 ❤️ + 45 🔴)

Phase 5 demo

[5a « 1b] Egg

The egg must now have an explicit attack, speed, and eggxperience stat.

  • The attack stat refers to how much damage the egg deals whenever you press the L button. From Phase 1, this currently has a fixed value of 1.
  • The speed stat refers to how many pixels the egg moves in either the x- or y-direction in one frame. From Phase 1, this currently has a fixed value (that you set).
  • The eggxperience stat is initially set to 0, and increases as the egg defeats eggnemies. For now, defeating an eggnemy must give 1 eggxperience.

The egg's attack, speed, and eggxperience stats must be shown in-game.

  • The egg has attack, speed, and eggxperience stats.
  • The egg's attack, speed, and eggxperience stats are explicitly shown in-game.

[5b] Egghancements

Every time the egg obtains a fixed amount of eggxperience, it unlocks an egghancement; the player can choose from one of 3 egghancements it can give the egg:

  • [1] Increase the egg's max HP by a fixed amount,
  • [2] Increase the egg's attack by a fixed amount,
  • [3] Increase the egg's speed by a fixed amount,

The player must press either the 1 key, the 2 key, or the 3 key to select an egghancement. Note that the player cannot choose more than one egghancement at once (i.e., pressing more than one of the keys at once shouldn't work).

Gameplay must be paused while the player is choosing an egghancement; the egg, eggnemies, and the boss (if present) must not move, and the timer must not be ticking up.

A window must appear at the center of the screen asking the player to choose an egghancement, as well as showing the possible egghancements they can choose from.

Note that increasing the egg's max HP by \(k\) also increases its current HP by \(k\).

  • Egghancements exist.
  • Gameplay is paused when an egghancement is unlocked.
  • A window pops up prompting the player to choose an egghancement, as well as showing them the 3 possible egghancements they can choose from.
  • The player can choose an egghancement via the 1, 2, and 3 keys.
  • Egghancements work (i.e., they actually affect the egg's stats).

[5c « 1f] Settings

The settings.toml file must have the following additional entries:

  • The egg's initial attack.
  • The egg's initial speed.
  • The amount of eggxperience needed to unlock one egghancement.
  • The increase in max HP given by the first kind of egghancement.
  • The increase in attack given by the first kind of egghancement.
  • The increase in speed given by the first kind of egghancement.

  • A settings.toml or example.settings.toml file exists, which sets all of the necessary values.

Phase 6 (45 ❤️ + 55 🔴)

Phase 6 demo

[6a] Eggnemies, Boss

Eggnemies and bosses must now have explicit attack and speed stats, just like the egg, but these stats do not need to be shown on the screen.

  • Eggnemies and bosses have attack and speed stats.

[6b « 3a, 3b] Progression

From this phase onwards, once the boss is defeated, the game does not end; instead, new eggnemies and bosses keep spawning until the egg is defeated.

Instead of spawning after \(x\) eggnemies are defeated, a boss must spawn for every \(x\) eggnemies that are defeated.

Every time a boss is defeated, subsequent eggnemies and bosses that spawn must have higher HP, attack, and speed stats. For this phase, you are free to set how much these stats increase.

The concept of a run's score will also change; now, the longer the run, the better. The leaderboard should be updated to reflect this.

  • The game only ends when the egg is defeated.
  • A boss spawns every time a fixed number of eggnemies is defeated.
  • Eggnemies and bosses get stronger every time a boss is defeated.
  • The leaderboard contains the longest runs instead of the shortest ones.

[6c « 3c] Tests

For this phase, you are required to have at least 15 test_* functions across your test_*.py files.

Different test_* files must still test meaningfully different aspects of your code.

Of course, all of the existing tests must pass.

  • Enough tests exist.
  • All tests pass.

[6d « 5c] Settings

The settings.toml file must have the following additional entries:

  • An initial eggnemy's attack.
  • An initial eggnemy's speed.
  • An initial boss' attack.
  • An initial boss' speed.

The entry that previously referred to the number of defeated eggnemies needed before the boss appears should now refer to the number of defeated eggnemies needed before a boss appears.

  • A settings.toml or example.settings.toml file exists, which sets all of the necessary values.

Phase 7 (45 ❤️ + 70 🔴)

Phase 7 demo

Note that from this phase onwards, you have a lot more creative freedom. The requirements will be more abstract, and we are encouraging you to be as imaginative as possible.

[7a « 5a, 6a] Sprites

There must now be a Pyxel resource file (.pyxres) used for graphics and sounds.

The egg, eggnemies, and the boss must now have their own sprites, which are distinguishable from each other.

  • A .pyxres file exists, and contains graphics.
  • The egg has its own sprite.
  • The eggnemy has its own sprite.
  • The boss has its own sprite.

[7b] Sounds

There must be sound effects for the following events:

  • A boss being defeated.
  • An egghancement being unlocked.
  • The egg being defeated.

Sound effects must be relatively short (or at least, appropriately long).

  • A .pyxres file exists, and contains sounds.
  • There is a sound effect every time a boss is defeated.
  • There is a sound effect every time an egghancement is unlocked.
  • There is a sound effect every time the egg is defeated.

Phase 8 (45 ❤️ + 85 🔴)

[8a « 1a] World

So far, the world has been constrained to a limited region. For this phase, the world should now be infinite.

Additionally, the world should now have obstacles that neither the egg nor eggnemies can pass through. These obstacles may be placed randomly.

Finally, your world must now be more interesting than an infinite black box. You are expected to use a tilemap to design the world.

  • The world is now infinite.
  • The world has randomly generated obstacles.
  • The world is not just a black background.

[8b « 7a] Eggnemies

It wouldn't really make sense to have eggnemies "spawn randomly in the world" anymore, since the world is now infinite! (Formally, if you choose a random integer in the range \((-\infty, \infty)\), the probability of choosing any particular integer is \(0\).)

Instead, eggnemies must now spawn around the player.

  • Eggnemies now spawn around the player.

Phase 9 (45 ❤️ + 100 🔴)

[9a « 7a] Boss

Bosses so far have just been "eggnemies with better stats"; this is the phase where you make them more interesting!

The first boss may still be the same, normal boss as in previous phases.

The second boss onwards must now have projectile attacks. A projectile is just yet another rectangle (albeit smaller, unless you want to make it big), which may have its own sprite. Projectiles must move in one direction infinitely. Projectiles must disappear once they come into contact with the egg.

The third boss onwards must now be able to spawn minions. A minion may behave like an eggnemy, with or without different stats. It must be visually distinguishable from eggnemies, though.

  • The second boss onwards must have projectile attacks.
  • Projectiles must behave properly (move in one direction, disappear upon hitting egg)
  • The third boss onwards must be able to spawn minions.
  • Minions must be distinguishable from eggnemies.

Phase 10 (60 ❤️ + 100 🔴)

So far, there has only been one kind of eggnemy and one kind of boss. To make the game more interesting, the game needs to support more of them!

We say that two eggnemies are of different kinds if all of the following things are true:

  • Their base HP is different.
  • Their base attack is different.
  • Their base speed is different.
  • At least one of the following is true:
  • One kind does not shoot projectiles, while the other does.
  • One kind does not spawn minions, while the other does.

Your game in this phase must now support at least 3 kinds of eggnemies and at least 3 kinds of bosses. When these eggnemies and bosses appear is up to you.

If you are unsure if your idea for a new kind of eggnemy or boss is sufficiently different, please consult the CS 12 team.

  • There are at least 3 kinds of eggnemies.
  • There are at least 3 kinds of bosses.

Phase 11 (75 ❤️ + 100 🔴)

So far, the game's objective has been straightforward: survive as long as possible as eggnemies and bosses keep spawning.

For this phase, you must come up with additional game modes you can play Egg Rally in. For the purposes of this project, a game mode must have two things:

  • A fundamentally different scoring system, and
  • Fundamentally different win and lose conditions.

You are expected to come up with 3 game modes, including the one that already exists.

If you are unsure if your idea for a new game mode is sufficiently different, please consult the CS 12 team.

  • There are at least 3 game modes.
  • The game modes are sufficiently different from each other.

Phase 12 (90 ❤️ + 100 🔴)

So far, the eggnemies and bosses have just been...following you around.

For this phase, your goal is to make the enemies smarter. For the purposes of this project, the enemies are considered smarter if they have behavior that is dependent on both (1) their own stats and position and (2) the egg's stats and position.

If you are unsure if your idea for enemies' "smart" AI is sufficiently different, please consult the CS 12 team.

  • The eggnemies must have "smart" AI.
  • The boss must have "smart" AI.

Final Phase (100 ❤️ + 100 🔴)

Surprise us! : )