CS 112 - Introduction to Computer Science II 4th Hour Project: Flutter Traffic Lights Game

---

Due: Monday, November 28 before class 37.

NOTE: This work is to be done in pairs.  I strongly recommend the practice of Pair Programming described simply here.  Although team members are permitted to divide work, each team member should be able to informally present all work of his/her teammate.

Flutter Development of the Traffic Lights Game

There is only one actual due date for this project (see above).  Part of the learning experience here is to pace your own work towards a larger goal.  I'll make suggestions as to how one might break up the work and spread out your effort, but a large part of successful work practice is the ability to give priority to important, non-urgent tasks over unimportant, urgent tasks. This point is well-described in Covey, Merrill, and Merrill's book First Things First, where they assert that work effectiveness is highly correlated with predominance of "compass-driven" important, non-urgent activity over "clock-driven" unimportant, urgent activity.  For larger college projects, especially those that will develop important skills or open new doors, one needs to develop an ability to plan and track important tasks so as to avoid procrastination and thus reduce resulting important, urgent activity.  See also Brian Tracy's relevant book Eat That Frog!: 21 Great Ways to Stop Procrastinating and Get More Done in Less Time. For an excellent book on forming and breaking habits, I recommend James Clear's Atomic Habits.

Suggested Outline of Work (resources and specifications below):

• Part 1 (ending class 16, 10/3): Learn about the Traffic Lights Game. Complete a working Flutter Tic-Tac-Toe App according to my tutorial.
• Part 2 (ending class 22, 10/19): Create/obtain your Traffic Lights Game project images. Create a new Flutter project that starts as a copy of your Flutter Tic-Tac_Toe, rename tic_tac_toe_state.dart to traffic_lights_state.dart and make all game state implementation changes necessary to model the Traffic Lights Game. Test and debug your model.
• Part 3 (ending class 28, 11/2): Modify your main.dart to now have a 4 row, 3 column layout and interact with your TrafficLightsState object, not forgetting to list your new image assets in pubspec.yaml. Your app should now work in emulation.
• Part 4 (ending class 31, 11/9): Export your Flutter app as an Android .apk file that can be downloaded and installed from your ~/public_html folder or subfolder. If you don't have a device for installation and testing, see me and I'll help you test it. See me for demonstration and improvement suggestions (if needed).
• Part 5 (ending class 37, 11/28): Export your Flutter app as a .html web app (JavaScript/HTML) and make it available via your ~/public_html folder or subfolder. Email me the URLs (web addresses) of your .apk and .html exports for grading.

Objectives

• Learn basic Flutter multiplatform 2D game development skills.
• Practice a discipline of regular progress on a project spread out over several weeks.
• Create and deploy the 3x4 version of the Traffics Lights game by Alan Parr for both browser and Android play.

Traffic Lights Game

The game Traffic Lights, originally called Semaphore, was invented by Alan Parr.  Reported years of invention/publication vary from 1985 to 1992 to 1998.  We will focus on the 3-by-4 version of the game.

Each square of a 3-by-4 grid is considered to be a light, initially off.  Players alternate selecting a square that does not show a red light.

• If the selected square's light is off, it turns on as a green light.
• If the selected square's light is green, it becomes yellow.
• If the selected square's light is yellow, it becomes red and can no longer be selected.

The first player that makes three lights on in a row/column/diagonal of the same green/yellow/red color wins.  (Played perfectly, 3-by-4 Traffic Lights is a 2nd-player win.)

Here are sources where you can learn more about the game:

• João Pedro Neto's Traffic Lights webpage
• BoardGameGeek Traffic Lights webpage
• João Pedro Neto and Jorge Nuno Silva's Mathematical Games Abstract Games book entry (PDF)

Installing Flutter / Dart

Since Google no longer designs its development environments to be suited for shared installation, we are recommending that students install Flutter and Dart on their own personal computers. If you do not have access to a suitable machine, contact the instructor for options.

There are a number of popular integrated development environments (IDEs) for Flutter development. Since one needs Android Studio for Android device emulation, one can simply use the Android Studio IDE with the Flutter plugin. Others prefer Visual Studio Code (VS Code) with the Flutter extension. The choice is up to you. I have tested that our project may be developed with the same steps on either.

Flutter Tic-Tac-Toe Tutorial

There are several online tutorials for implementing Tic-Tac-Toe in Flutter that feature smooth presentation and yet have bad code design. I therefore decided that it would be better for you to have a not-so-smooth presentation with good code design. In particular, I demonstrate the important coding discipline of separating model/logic code from interface code. In both the tutorial and your later implementation of Traffic Lights, the separate concerns of modeling the game and creating the interface to the game are pointedly separated into different files. The game logic file is only Dart without Flutter. Flutter builds its interface on the Dart language, but one ideally shouldn't involve Flutter in the implementation of the game logic.

These videos are flawed, with occasional bugs being introduced by well meaning VS Code autocompletion. At one point, if you see me having difficulty typing an underscore, my keyboard had mysteriously slipped into Spanish mode. :) However, these one-take videos reach the goal and explain the code along the way. You should code along with them at your preferred pace.

Before starting the video, you should create a new Flutter project and make sure it runs properly. The steps are specific to your IDE, so you'll need to do some web searching for a walkthrough of the process.

• tic_tac_toe_state.dart (48:45) - In this video, you'll implement tic_tac_toe_state.dart that defines class TicTacToeState, the game logic foundation of our implementation. (The system "autocorrected" my filename to tic_tac_toe_tutorial.dart, but this is corrected in the following video. These less-than-100 lines of code provide a decent snapshot to the syntax of Dart, but you can also benefit from the Dart language tour or one of the Dart Codelabs.

• main.dart (1:09:59) - In this video, you'll reimplement main.dart to provide an interface to playing with your TicTacToeState object. The main interface building code is really just a single, deeply nested collection of widget constructions. The hierarchy of the widget tree is reflected in the code nesting.

  You'll need to create "assets" and "assets/images" subfolders to contain the needed PNG image files, and modify your project pubspec.yaml to list these images in their locations as shown in the video. For brevity, I do not get into the details of each widget I use, but you can supplement your learning with Flutter Codelabs and find documentation for the main classes/widgets used through these direct linhelpful direct links to used widget documentation here:

  • AppBar
  • AspectRatio
  • BoxConstraints
  • Center
  • Column
  • ConstrainedBox
  • Container
  • EdgeInsets
  • ElevatedButton
  • FittedBox
  • Flexible
  • GridView
  • Image
  • Scaffold
  • SliverGridDelegateWithFixedCrossAxisCount
  • Spacer
  • Stack
  • StatefulWidget
  • StatelessWidget
  • Text
  • TextButton
  • TextStyle

  Images and Game Layout

  Create/legally-obtain your project images for your green, yellow, and red lights. Your design should be color-blind-friendly in some form and should respect copyright.  Color differentiability can be tested through sites such as the Colblindor Color Blindness Simulator (Coblis), but you may also address this design concern through the use of shapes as seen in this game image.  (Note how the shapes are cleverly iconic, bringing to mind a circular green light, a triangular yellow yield sign, and an octagonal red stop sign.  For more on color palette design for the color blind, see this article.

  Modify your main.dart from the Tic-Tac-Toe tutorial to have a portrait 4 row, 3 column grid layout, incorporate your new images (don't forget pubspec.yaml listing of image assets), and have the interface work with your TrafficLightsState object that you've adapted from your TicTacToeState object.

  While I ask you to give careful consideration of color-blind-friendly design, do not spend too much time on creating your images. I like to recall that many of our students at one time were into a new game called Kingdom of Loathing that was developed in a weekend and incorporated scanned, hand-drawn stick figures as graphics. If you want to hand-draw your icons with crayons, take pictures of them, and scale/crop them to a 1:1 ratio, go for it!

Game End and Restart

As with Tic-Tac-Toe, your Traffic Lights game logic the ability to detect a winning three-in-a-row in any row, column, or diagonal line of the board.  Note that there are 14 3-in-a-row possibilities for each of 3 colors, so you'll need to list these.

Clearly indicate a win. This can be through display of a status message.  An optional clear improvement would be to indicate 3-in-a-rows with lines/shading/etc., but do not attempt this extra layer of complexity until all phases of your project are complete and correct.

Allow the user a means of restarting the game, e.g. our Tic-Tac-Toe Reset button.

Traffic Lights players are "1" and "2", not "X" and "O". Always have Player 1 start the game.

Add a Player Turn Indicator

Clearly indicate whether it is Player 1's turn or Player 2's turn. Again, this can be accomplished through a game status message.

Critique and Improve

Playtest your game a lot.  Make it a game implementation you would want to play.  This is the Golden Rule of programming.

Android and HTML Deployment

Since details will differ with different development environments, I will not list details of this process here. However, it is important to understand that you will not need to submit your work to any app store or deploy it through a third-party website. For Android deployment, you need to build .apk files and put them somewhere within your public_html directory. Likewise for web deployment, you'll generate a directory containing an index.html file with supporting files.

To set permissions such that everything in your public_html folder is publicly accessible, use the recursive command "chmod -R 755 ~/public_html".  Whatever is in your public_html folder will be visible via "http://cs.gettysburg.edu/~<your username>". Note that you'll also need to edit your index.html file to indicate its root directory. Within the index.html file of my sample HTML build at http://cs.gettysburg.edu/~tneller/cs112/flutter/trafficlights/, I needed to edit line <base href="/"> to reflect its address: <base href="/~tneller/cs112/flutter/trafficlights/">

It is not necessary to create custom icons/titles/app names, but there are many sources that can be helpful to put that final polish on your app deployment:

• Changing the app icon: StackOverflow question, Generating icon images
• Changing the app name in Flutter
• Summary of above
• If you find other helpful resources for deployment, please share them with me.

Sample Builds

• HTML
• Android .apk files

Grading Demo Appointment

During the week of the due date, teams will schedule a 30-minute appointment for demonstration and testing of:

• Your TicTacToe tutorial implementation emulated or demonstrated on a device
• Browser play of Traffic Lights
• Android play of Traffic Lights (See me in advance to download your work onto a department Android tablet/phone if you do not have an Android device.)
• Flutter Traffic Lights code review

Grading Rubric (20 points total):

• 4 points: Successful Tic-Tac-Toe tutorial completion
• 5 points: Layout and graphics - 4 row, 3 column board layout and lights clearly show the game state and design is friendly to the color-blind.
• 5 points: Game logic - game rules are correctly implemented, game victory is correctly detected and clearly indicated, player turn is clearly indicated.
• 3 points: HTML game deployment - The game can be played via a browser directed to a URL within one's ~/public_html directory or subdirectory.
• 3 points: Android game deployment - Android .apk file can be downloaded and installed from an indicated path in one's ~/public_html directory or subdirectory.