Project-L

Functional Specification

Overview

This project is a Unity implementation of the Project L board game published by Boardcubator. It is a strategy game designed for 2-4 players, in which the players solve puzzles and collect tetrominos. You can either play against your friends or you can create your own AI players and play against them. Or both!

This spec doesn’t discuss the technical side of things (how it works). If you are interested in that, please read the Technical Documentation.

Scenarios

Alice and her friend Charlie want to try a new strategic game and so Alice decides to fire up her newest discovery - Project L. After reading the user guide, they are ready to play. They simply create a new game, add two players named Alice and Charlie and soon they are solving puzzles and building their tetromino piece collection.

The next day, Alice decides to also invite her friend Karel to play with them. Karel is studying computer science, so when Alice starts creating a new game, he gets immediately interested by the option of adding AI players to the game. During the weekend, he reads the AI player creation guide, implements the necessary interface, exports his project as a DLL and now he is ready to play against his own creation.

Non Goals

This project will not support the following features:

Screen by Screen Specification

The game consists of a couple of different screens which Alice and Charlie will encounter when playing the game. First they will see the Start Screen, where they can create a new game or view the user guide. After that, they will be taken to the New Game screen, where they can add players and set up the game. Once they are ready, they will be taken to the Main Game screen, where they will play the game. Finally, when the game is over, they will be taken to the Final Results screen, where they can see the results of the game and buy the winner a nice trophy.

Screens are referred to by their canonical names, always underlined in this document, e.g. Start Screen.

Table of Contents

Start Screen

The first thing Alice and Charlie will see when they start the game is the following:

Start Screen

The Start Screen contains the buttons:

Credits

After trying out what the CREDITS button in the Start Screen does, Alice and Charlie ended up here:

Credits

They don’t want to read a novel but to play a game and so they click on the arrow in the bottom left corner to get back to the Start Screen.

New Game

Karel created his own AI player which uses the NEAT algorithm to decide the next action. After clicking the NEW GAME button in the Start Screen he was taken here.

New Game

Karel added his NEAT player to the INI file defining available AI players, as specified in the AI Player Guide. He wants to test if it works correctly by playing a game against it.

He clicks on the dropdown menu for the type of the first player, selects “Human” and enters his name. From the dropdown menu for the second player he chooses “NEAT” and come ups with a name for it.

He then uses the slider below to set the initial amount of pieces of each type in the shared reserve and decides he wants to shuffle the players to make things more interesting.

After that he just hits “Start game” and is taken to the Main Game screen.

If Alice had a change of heart and wanted to read the credits, she could click on the arrow in the bottom left corner to go back to the Start Screen.

Player selection in detail

The game can can be played by a maximum of 4 players and a minimum of 1 player (it might not be very interesting though). To add a player, Karel needs to select a type from the dropdown menu and add a name.

Once at least one parameter for a player is set, the reset button will appear to the right of their name. The player information can then be cleared by clicking on it. The game cannot be started until at least one player is added. If a player is only partially defined (e.g. only a name is set), the game cannot be started either.

The number of starting pieces in the shared reserve is 15 by default (the value in the original game), but can be adjusted using a slider below the player selection. The minimum number of pieces is 10, the maximum is 30 and the tick interval is 5.

Players are shuffled by default to ensure random order of play. This can be turned off by unchecking the checkbox below the player selection. In that case, the order of play is specified by the numbers left of the players in the New Game screen.

Main Game

After Karel is done creating the game for him, Alice and his NEAT algorithm AI player, he clicks on the Start game button and is taken to the Main Game screen. After playing for a while, he takes a screenshot of the game to show it to his friends.

Main Game

AI Player Initialization Errors

When the game starts, an initialization method is called for all AI players in the game. If an AI player fails to initialize (an exception is thrown), the game will announce that it cannot continue and will return to the Start Screen.

Main Game Zones

The Main Game screen is subdivided into multiple subsections as seen in the image below.

Main Game Zones

Player Zone

Contains the unfinished puzzles of each player.

Piece Zone

Contains information about the number of pieces owned by each player and the number of pieces left in the shared reserve. It consists of several columns which from left to right are:

For example, NEAT has 3 L2 pieces, Karel has 1, Alice has 0 and there are 8 left in the shared reserve.

The pieces the current player (Karel) doesn’t have are grayed out. For example, the shapes which aren’t grayed out on the reference image are O1, L2, I3, I4, because Karel has them in his collection.

Puzzle Zone

Consists of the following:

When either of the decks become empty, the corresponding Deck Card will disappear. If it is the black deck, the end of the game will be triggered.

Action Zones

Located above the Puzzle Zone and Piece Zone and used for creating actions. The Puzzle Action Zone contains:

The Piece Action Zone contains:

When the game comes to the Finishing Touches phase, the End Finishing Touches buttons appear in both of the Action Zones. They replace all other buttons (including the confirm buttons) which were there originally.

Creating Actions

When Alice first enters the Main Game screen, she has no puzzles, so for her first action she decides to take a puzzle from the Puzzle Zone. She clicks on Take Puzzle, selects a puzzle by clicking on it, confirms her selection, and the puzzle appears in her row in the Player Zone.

Now she would like to complete the puzzle to get the reward. Thankfully, every player gets two pieces (O1 and I2) at the start of the game. She decides to place the I2 piece, so she drags it onto the puzzle using her mouse. Then she rotates the piece with the mouse wheel and once she’s happy with the position, she clicks to lock it in place. After contemplating for a bit, she changes her mind about the placement, so she drags the piece to a new position, locks it in place and confirms her action.

Creating Actions in Detail

The general process of creating an action is as follows:

  1. Start dragging a piece from the Piece Zone to use the Place action or click the appropriate button in the Action Zones to use any of the other actions.
  2. After a valid action is created, the Confirm buttons will be enabled. Clicking on one of them will confirm the action and the game will be updated accordingly. The action can also be confirmed by pressing the Enter key on your keyboard.

Once you click an action button in the Action Zone, it will be highlighted. Clicking on it again will unselect it and cancel the action creation process. Clicking on a different action button is equivalent to pressing the selected button again and then clicking on the new action button.

AI player actions are visualized in the same way as human player actions. If an AI player fails to provide a valid action, the game will simply ignore it (skip it).

Place Piece

Drag a piece you own from the Piece Zone to the Player Zone and place it on a puzzle. The piece will be highlighted.

You can do the following with the piece:

When a piece is placed, it can then be dragged again and moved to a different position. This can be repeated until the action is confirmed.

To plan ahead, you can move all the pieces you own from the Piece Zone to the Player Zone and position them on the puzzles as you wish. For example, Karel could use two O1 pieces, one L2 piece, one I3 piece and one I4 piece. A place action is valid if and only if exactly one of the piece is placed. All other pieces will return to your collection when the action is confirmed.

Dragging pieces away from the Piece Zone decreases the corresponding numbers in your column and the number also turns red. If a number would reach zero, the corresponding piece would become gray. If you dismissed a piece, the number would go back up, and the piece would get its color back. If the number reached its original value again, it would stop being red.

When happens if you complete the puzzle is discussed in the Completing Puzzles section.

Take Puzzle

Click the Take Puzzle button in the Puzzle Action Zone.

  1. All puzzle cards and the Deck Cards will be grayed out.
  2. To take a specific puzzle from the Puzzle Zone, simply click on it. To take the top puzzle from one of the puzzle decks, click on the corresponding Deck Card.
  3. The selected puzzle/card will be highlighted and you can change your mind until you confirm the action. Clicking on the same puzzle/card again will unselect it, while clicking on a different puzzle/card will change the selection.

Take Puzzle

After you confirm the action, the puzzle will be placed on the first empty slot in your row in the Player Zone. If you puzzle row is full (you have 4 unfinished puzzles), the Take Puzzle button will be disabled.

Recycle

Click the Recycle button in the Puzzle Action Zone and choose a column (white/black) to recycle.

  1. All puzzle Cards will be grayed out.
  2. Click on the puzzles in the column in the order you want to recycle them. The first puzzle will go to the bottom of the deck first etc.
  3. The puzzles you have clicked on will be highlighted. Clicking on a highlighted puzzle again will remove it from the selection and shift the recycle order. If there is a highlighted white puzzle, you can not add a black puzzle and vice versa.
  4. Once all puzzles of a certain color are selected, you can confirm the action.

Take Basic Piece

Click the Take Basic Piece button in the Piece Action Zone and confirm the action to get the O1 piece. The button will be disabled if there are no O1 pieces left in the shared reserve.

Upgrade

Alice wants to finish the puzzle in the right-most spot in her row and she needs just a L2 piece to do it. She doesn’t have one, but she has a I2 piece, which can be upgraded into it. So she presses the Upgrade button in the Piece Action Zone and selects the I2 piece in the Piece Zone. The I2 piece will be highlighted and all the pieces which she cannot change it to will be grayed out. She then selects the L2 piece, which highlights it as well and grays out all the other pieces. Once she is happy with her selection, she confirms the action. The I2 piece is removed from her collection and the L2 piece is added to it. The number of pieces in the shared reserve is updated accordingly.

Upgrade Piece

If Alice had a change of heart and decided to upgrade the I2 piece to a I3 piece instead, she could have clicked on the selected L2 piece again to unselect it and go back to the previous state.

Clicking directly the I2 again would unselect everything and go back to the initial state after pressing the Upgrade button. This is regardless of whether the I2 piece was already selected or not.

Master

Press the Master button in the Piece Action Zone and position your pieces in the same drag-and-drop manner as with the Place Piece action. The only difference is that the Master action is valid if and only if at most one piece is placed in each puzzle.

End Finishing Touches

As the rules say:

After the final round ends, each player may place any number of pieces from their supply into the puzzles in front of them following the normal rules for the Place action. For each piece placed this way, 1 point is deducted from that player’s final score.

The players don’t get any rewards for the puzzles they finish this way and they don’t get the used pieces back either. But they will not get the negative points, which are deducted for leaving some puzzles incomplete.

To perform Finishing touches, simply place all the pieces you with (and own) into your puzzles in the same manner as with the Place Piece action. You can place as many pieces as you want. Once you’re happy, end your turn by clicking the End Finishing Touches button in one of the Action Zones.

After everyone ends their Finishing touches, the game transitions to the Game Ended screen.

Completing Puzzles

After a puzzle is completed (all empty cells are filled in), it will be highlighted and the text “Select reward” will appear in the Control Zone. The pieces in the Piece Zone which you cannot take as a reward will be grayed out.

To choose a reward, click on the piece you want to take and it will be highlighted. If there are multiple options and you want to change your selection, simply click on a different piece. Clicking on the same piece again will unselect it. Once you are happy with your choice, click on the Confirm button in the Control Zone.

After you choose a reward, you will get the points for the puzzle and the pieces used to complete it. It is also removed from your row in the Player Zone.

In the very unlikely event that there are no pieces left in the shared reserve (and therefore there is no possible reward), you will not be prompted to choose a reward. Instead, the puzzle will be highlighted, you will be returned the used pieces and then it will be automatically removed from your row in the Player Zone.

Finishing Touches

If a puzzle is completed when the player presses the End Finishing Touches button, it will simply disappear from the Player Zone.

Main Game Pause Menu

When playing the game, Alice and Karel remember that games usually do something when you press the Esc key, and so they try it, all animations stop and the game pauses. They see the following screen:

Main Pause

Alice noticed that it says that the current player is Karel and has 2 actions left. There was also some message about the game phase, apparently it already was the Final round. Karel remained Alice about what they read in the rules:

When the Black puzzle deck is empty, the end of the game is triggered. Finish the current round and then play one final round. Then perform finishing touches and calculate the final scores.

After playing the game a few times the two of them discovered all of the different messages hidden in the Main Game Pause Menu.

There are three different buttons:

There is also a slider for adjusting the speed of animations of AI players and the end game animation (see Final Results). Minimum is 1x, maximum is 4x and the tick interval is 1.

If you want to peek at everyone’s score, you can do so by clicking on the closed eye icon left of the Score text. The eye will open and the scores will be shown. Clicking on the eye again will close it and hide the scores. The scores are hidden by default. If you exit the pause screen with the eye open, it will still be open (and score visible) when you come back.

Game Ended

After Karel, Alice and the NEAT player all perform their Finishing touches, they see the following screen:

Main ENd

Upon clicking the Calculate Score button, they are taken to the Final Results screen.

Final Results

Alice is eager to see who won, so she clicks on the Calculate Score button in the Game Ended screen and is taken to the Final Results screen. A fancy animation plays, showing all the puzzles each of the players completed, the pieces they used during finishing touches and the puzzles they failed to complete. The points are added and deducted from the score as the animation plays. However, Alice isn’t happy with the result, because she and the NEAT player have the same score, so she doesn’t know who won! The crisis is averted when the Num puzzles and Num pieces rows appear underneath, revealing that Alice has completed 8 puzzles, but NEAT completed only 7. Alice might have not won the game, but she beat Karel’s super cool AI player, so she is happy.

The HOME button (bottom right) takes Alice and Karel back to the Start Screen, where they can start a new game.

Final results

Final Results Pause Menu

Alice and Karel finish the next game (they can’t stop playing, it’s so good), but once they get to the Final Results screen, they are interrupted by a phone call from Karel’s mom. It’s already 2 AM and she wants to know if Karel is going to go to bed willingly or if she will need to employ more drastic measures. Karel wants to see the fancy final animation, so he pauses the game (Esc) not to miss it, and tells his mom that he will go to bed in a minute. He then resumes the game and the animation continues.

Final Results Pause

This site is open source. Improve this page.