Fall 1997, Professor Yap
V22.0201.002, Machine Organization I

FINAL PROJECT

Proposal Due: Wed Nov 19, 1997 (Next Week)
Project Due: Wed Dec 10, 1997 (Last Class)

INTRODUCTION

The project is to write a game playing program. It requires significant use of interrupts and text or video graphics (based on material in chapters 12, 15 and 16 of the text book). Many of your basic needs (random number generator, timer) will be provided. We also give examples of mouse and sound routines. The type of games you can program is really up to your imagination.

This year, I plan to make it easier for people to produce a substantial game without having to begin from scratch. I will provide you with several games (from previous classes), and you are to improve them in significant ways. Our grading will (TRY) not discriminate between whether you take this route or build a game from scratch. There are pluses and minuses, of course, which you can weigh. This will be posted by the end of this week.

What I would like to see in your games: interactivity, use of computer graphics and some real-time elements (i.e., the player need to respond within a reasonably short time span). Hence it is unlikely that I will approve a project to build a paint program or a screen saver! But check with me first.

We will grade you favorably if you impress us with something in your game. So do not be shy to tell us of any nice features you have!

YOU MUST KEEP THIS DOCUMENT WITH YOU THROUGHOUT THIS PROJECT FOR REFERENCE. WHEN IN DOUBT, ASK.

PROJECT TEAM

This project is to be accomplished by a team of 2 or 3 students. As I said, there are tradeoffs between having 3 (less work per person but perhaps ability to tackle a bigger project) or 2 (less problems of coordination and personality conflicts). To be successful, please be willing to be flexible and ``go the extra mile'' for your partner (you never know when you might need your partner's goodwill later). Remember: even if you have difficulties with each other, it may be to your advantage to cooperate. If there are problems you cannot resolve, please inform me and I will intervene.

PROPOSAL

You need to submit a proposal for your project. The proposal is worth 20 points [-10 points if you do not form your teams by Nov 17]. It can be submitted any time before MONDAY (November 24). You must submit the proposal by email. What is needed in your proposal:
  1. The length of your proposal should be about one type-written page (when printed).
  2. Names of team members (names and email)
  3. Title of project
  4. User level description of the game:
    1. What does the user see on the screen?
    2. What is the objective of the game?
    3. How does the user play? (buttons? keyboard?)
  5. IMPLEMENTATION PLAN:
    1. What video mode will you use? (Why?)
    2. What technical tools do you need? (set up interrupt vectors, need random number generator, need mouse, need sound, etc). You may need to read up chapters 12,15 and 16.
    3. What user friendly features will you implement? (online help, ability to set level of game, etc)
    4. Divide the effort into two parts: ``basic features'' of the game (that you know you can finish in time), and ``advanced features'' (if time permits). Be realistic even about ``advanced features''.
FORMAT AND POSTING OF PROPOSAL: I am going to post your proposal in a list for the rest of the class to view. Hence your proposal must be conform to a basic HTML format (ready for web posting). Here is a sample proposal format that EVERY ONE MUST USE (copy this file, and replace the contents with YOUR own proposal. Note that I intend to approve your proposal almost instantly by email, unless I find some problems. If your project starts to deviate from your proposal, you need to obtain my permission and perhaps resubmit a new proposal.

GENERAL PLANNING

Your project should be realistic for our time frame. It is STRONGLY RECOMMENDED THAT you may want to only implement the basic features of your game before trying to implement advanced features (see proposal above).

Try to allocate the last few days of the project to debugging, commenting and documentation. It is silly to work so hard on the programming part but then neglect this simple part which is easy to satisfy, and which carries a significant part of the grade.

We suggest that you each delay any other ``optional'' activities for at least the last 2 weeks of this project.

POINT ALLOCATION: Our goal is to make this grading process as predictable as possible. We will, as usual allocate a certain number of points to certain items. BUT some items are allocated negative points. E.g., the COVER PAGE of your report carries negative 20 points. This means that if you fail to provide an adequate cover page, up to 20 points are subtracted. But no positive points are allocated for the cover page. So your aim is to get 0 points for your cover page.

TO BE HANDED IN

Hand in the following 2 items in an envelop (sealed) with the following information: 
	FINAL PROJECT, V22.0201.003, Yap
	Your project name.
	Your team names
It is your responsibility to keep extra copies of what you hand in, and we suggest you put the envelop under my door rather than in the mail box (we had one lossage in hw3).

ITEM 1: REPORT

This item is a SINGLE document that is placed between proper covers [-5pts]. E.g., to get a SINGLE document, I prefer a book-type binding, but I could accept the use of binder clips.

You should prepare this report in the computer and these computer files must also be submitted (see item 2).

PROPER ENGLISH [-20pts]. Please take pride in what you write -- we want to emphasize that writing well is an important part of your education. Make sure that you write in English! For instance, each English sentence has a verb, not two and not zero, and ends in a full stop (I have seen ``sentences'' that violate such basic rules). NOTE: Sorry we have to say this. The grader reported some sloppy writing in your hw2 when you had to write some sentences.

The document must contain the following sections:

  1. COVER PAGE [-20pts]
    This contains
    (a) the course identification (including semester, year, instructor),
    (b) name of project,
    (c) Team Member Names,
    (d) ID's of each member,
    (e) email addresses (must have),
    (f) phones (optional).
    (g) Signature of each member,
    (h) and NOTHING ELSE.
  2. SECTION A: CONTENTS PAGE [5pts]
    (a) A table of contents of document.
    (b) A list of all the files in diskette.
    (c) Name of program modules and the PERSON(s) responsible for each module,
    (d) Full credits to code or help obtained from elsewhere. You must specify the source of any copied code, and tell us where is the original code in your diskette. If this is all original code, state the following "THIS IS ALL ORIGINAL CODE".
    (e) NOTHING ELSE.
  3. SECTION B: PROJECT OVERVIEW [10 pts]
    B.1. Introduction: this is up to you.
    B.2. The object of the game: this can be modified from your proposal.
    B.3. The user view of the game:
    this can be modified from your proposal.
    B.4. Highlight any interesting or special achievements.
  4. SECTION C: USER INSTRUCTIONS [10 pts]
    C.1. How to install game (including requirements).
    C.2. How to execute your program and play game.
    Include instructions for quick EXIT from the game (typing ESCAPE, for instance [-4pts]. C.3. Any features or hints for users to know about. Tell the user of possible problems here.
  5. SECTION D: TECHNICAL PORTION [10 pts]
    D.1. High-level technical description of your project (1-5 pages). What kind of graphics, sound, mouse or other routines. If you have done something nice, this is the place to tell me! Here are some things of interest to us: D.2. Summary of the different assembly modules: how they are organized and related to each other. What are the key functions in each module.
  6. SECTION E: CONCLUSION [5 pts]
    Describe suggestions for future work (if had time, say). Give suggestions about how you might do things differently (a future student in this class may be able to benefit from your experience). Include any interesting experience while doing this.
  7. APPENDIX I: ORIGINAL ASSIGNMENT [2 pts]
    Just a copy of this document.
  8. APPENDIX II: ORIGINAL PROPOSAL [2 pts]
    Attache any any approved modifications as well.
  9. APPENDIX III: COMPLETE GAME PROGRAM [5 pts]
    Copy of well-commented programs. Each file should begin on a new page with the name of the file at the first line. If you have 5 files, say, then you will have subsections III.1, III.2,..., III.5.
  10. APPENDIX IV: ORIGINAL SOURCES [-100 pts]
    Copy of any programs that are not your own, that you have used or modified for your project. Include information on your source (e.g., ftp site where you downloaded the code). You do not need to include any programs taken from our text book or which are provided by me.
Each section must begin with a new page. No section or part may be omitted. For instance, if you have nothing to say in Subsection B.1, then insert the sentence "Subsection B.1 is not applicable" (for instance).

ITEM 2: DISKETTE

The second item in the envelop is a 3.5'' diskette containing the following information and files [20 pts].

  1. Label on diskette with class identification, your team names and project name [-6 pts]. REMEMBER THAT WE GRADE MANY PROJECTS AND IT IS EASY TO MIX UP DISKETTES FROM DIFFERENT PROJECTS.
  2. SUGGESTED FINAL CHECK: try to assemble your game and play the game using the diskette which you hand in. Common mistakes include: (a) some crucial files are missing, (b) you hand in the test version of a game, (c) you hand in a debugging version of your asm.bat file.
  3. At the top level, we only want to see the following [-10pta]:
  4. [10pts] The file README.TXT can be the COVER PAGE and SECTIONS A and B of your report above.
  5. The subdirectory called DOC contains your complete report (ITEM 1 above), except for program files which are already stored in the SRC subdirectory. I prefer the files to be plain text, but if you like, something like MS Word is fine.
  6. In SRC: the main module MUST be called GAME.ASM [-4pts].
  7. In SRC: there is a macro library called MYMAC.LIB [4pts]. Of course, we expect you to use this library whenever possible.
  8. I want you to break up the game into several modules [8pts]. However, do not have more than 10 modules. All the module name should begin with the letter `G'. E.g., the modules might be 
    		GAME.ASM, G_GRAFIX.ASM, G_SOUND.ASM, G_INPUT.ASM
    that corresponds to the main module, graphics sound, and input for the game, etc. Each module must belong to a team member who has the primary responsibility for it. The initial comments for the module should give this information.
  9. A subdirectory called BIN which contains your executables [-10pts].
  10. BIN contain an executable called GAME.EXE must be present [-10pts].
  11. BIN contains a bat file called ASM.BAT to assemble your game [2pts]. For instance, if your files are as in the above example, then the ASM.BAT file might look like this: 
    		TASM GAME + G_GRAFIX + G_SOUND + G_INPUT
		TLINK GAME + G_GRAFIX + G_SOUND + G_INPUT
    This file is for us, as well as for your own use. (For your own debugging, you might want to write another file DB.BAT which calls TASM with /zi, /z flags, etc, and calling the turbo debugger TD.)
  12. BIN contains a bat file called GO.BAT which calls your GAME.EXE [2pts]. For many students, the GO.BAT file simply contains the line "GAME.EXE". But if your game needs to load the TSR program RANDOM.COM which we provide, then your GO.BAT file might contain the lines 
    		RANDOM.COM
		GAME.EXE
    Some other games might have even more fancy setup.
  13. [-20 points] On the first screen of EVERY game, the user should see this information: 
    	<TITLE OF GAME>

	<NAME OF TEAM MEMBERS>
	
	Machine Org I, V22.0201.002, Fall 1997

	CREDITS: 
		<...if you borrow code for anyone or source...>
		<...or owe thanks to...>

	<You may put other information here, if appropriate>
  14. If you have used programs or substantial fragments of code from other sources, please put them all under a subdirectory called SOURCES [-80pts].
  15. If your game requires data files, or will produce files, please put them all under a subdirectory called DATA [-4pts]. But files should be explained in the CONTENTS SECTION of the REPORT.
  16. NO UNRELATED FILES may be on your disk [-10pts]. If you like, you can have a subdirectory called OTHERS, and put everything else there. E.g., hw1.asm, etc, should be in OTHERS.

GRADING

Besides the points already allocated for the above items, we allocate the following points:
  1. If your game works properly, and implements all the basic features in your proposal, you automatically get 100 points. If it works only partially, you get parts of 100 points. You get 0 points if there are assembly errors. In view of this, I suggest that you take our suggestion to initially focus your effort on the ``basic game''.
  2. Online documentation [20 pts]: what we mean is that when I execute your program, I will get an initial introduction to your game (its name, its objectives, and how to play it). This can be as simple as printing a page of instructions at the beginning of the game.
  3. We allocate up to 30 points for additional game features beyond your basic game. Be sure to tell us about them!
  4. We allocate up to 20 points for making the game more user friendly. For example:
  5. Comments and Inline documentation within the files [25 pts]. We look for overall description of the modules, the procedures that you have written and how they call each other, etc. We normally do not read your code -- but based on your high level descriptions, we may poke inside your code... etc.

NOTES

  1. Please be aware that your game will be used for my educational goals in future courses. E.g., I will use it for demonstrations and possibly put the code out for future students to modify and improve.
  2. Instructions are strict: It is hard to believe, but I had students who do not submit proposals and are in no team. At the last moment they hand me a diskette (from a team of one). This guarantees an automatic 0 for the project.
  3. Code re-use: It should be clear that we encourage you to reuse code you find elsewhere, provided you do something new and creative with it. Here are some caveats.
    First, you should take over a major piece of code, do some minor changes to it, and claim it is your own. This is very serious plagiarism and a university disciplinary problem.
    Second, never use a piece of code without fully understanding it yourself.
  4. Debugging: re-read debugging instructions from our FAQs page. You will need to do debugging more than ever. Test each procedure before you proceed to writing the next one. It should be easy to do this by writing a small main program (the book has many such examples). Go into the debugger to see what your procedure is doing. Keep these test main programs around (but put them in the subdirectory OTHERS), in case you want to modify your procedures later!