Design+Code 3: Engine Fixes

Our rapid pace of work on sald has left it with a few rough edges. We're going to spend this week smoothing them out.

There are four separate projects (A, B, C, and D below). You will randomly assigned a letter and a symbol. The letter is your project, the symbol determines your two-player partner.

Design Phase

Please feel free to ask clarifying questions at any point.

(20 minutes; Single Player) Read the code and any available documentation for the subsystem you will be working on. Read and understand what I want you to fix.

(20 minutes; Two Player; circle with circle, square with square) come up with at least three strategies to fix the code. Create a diagram or brief, written description of each.

(remaining time; Four Player) debate the possible strategies, and select one for implementation. Be sure to address the questions in the "Design Considerations" section of your assigned project. Write a brief specification for your proposed changes, including a rough outline of the functions and data that will be used/changed. Assign group members to each part of the task.

What To Turn In (Design Phase)

Each group should meet with me to discuss their specification and allocation of work. After this discussion, I will ask that one member of the group send me a summary of their proposed changes and work allocation via e-mail. This will be the deliverable for the design phase.

Coding Phase

Once I have signed off on your specification, work on implementing the changes you have specified. Start by producing a skeleton for your code -- functions and descriptions of their operation -- before working on filling it in. Make sure to leave plenty of time for testing.

On Thursday, I will meet with each group for progress updates and clarifications. Please work to have some progress to update me on.

What To Turn In (Coding Phase)

Each group should submit a pull request for a single github repository containing their fixes. Make sure that this repository has a commit log that clearly identifies who originated each piece of code. If pair- or group- programming, please make a note in your commit messages.

I will be grading each group's result as a single entity. If the code works and addresses (or refutes) my concerns, it will be counted as complete (1 point). If the code does not work or fails to address my concerns, but appears to make a good effort, I will mark it as partially complete (0.5 points). If I do not receive a pull request, or the submitted code seems incomplete, I will mark it as incomplete (0 points).

Group A: Build System Overhaul

Sald's build system is the core of the engine. It is responsible for transforming the game developer's files and assets [and their dependencies, specified using the require() construct] into javascript for inclusion in a single html page. It performs this transformation using transform functions, of which several defaults are provided.

• Transforms should act on require'd strings (not -- explicitly -- files). E.g., a game developer should be able to implement a transform such that require('gradient:#000-#fff') returns a build-time-generated gradient.
• Transforms should output javascript which is scanned for more require() statements. E.g., a game developer should be able to implement a transform that does globbing by returning module.exports = [require('imgs/1.png'), require('imgs/b.png')]; as the transformed version of 'imgs/*.png'.
• NOTE: the above requires that transforms are able to indicate the appropriate path for their generated javascript, such that any require() statements therein work as expected.
• NOTE: currently require('sald:library.js')-style requires are special-cased. They should be implemented as a transform.
• If the same thing is required in two different ways, only one chunk of code should be generated. E.g. require('lib.js') and require('./lib.js') should result in only one inclusion of the code from lib.js; similarly, continuing the example above, require('gradient:#000-#fff') and require('gradient:black-white') might also only result in one gradient being created and included.
• Default transformations for images and audio should live in sald instead of being read from each project's build.js. There should still be an example transformation in build.js, but it should be something that, e.g., triggers on require('helloworld:') and produces output code module.exports = "Hello World";.
• The build.html produced for a given project should not vary from computer to computer or run to run.

Design-Phase Considerations

• What is the signature of a transformation function?
• How is de-duplication of the same thing require'd with different strings performed?
• What common activities performed by transformation functions should be made into (developer-accessible) helpers?

Coding-Phase Deliverables

• Modify the build system to include the fixes above. This will likely require an extensive restructuring of compiler.js
• Create developer documentation in README.md that includes the specification of a transform function -- including how to do error handling.
• Create an example project with transforms that generate data, call shell scripts, and override default transforms. This example project should live in its own repository.

Group B: Sprite Library

Sald's Sprite Library seems to support displaying windows within a sprite image or image list passed to it. However, based on my read-through, it needs some fixes:

• There is no documentation or example code.
• Argument processing seems somewhat complex. Can it be simplified?
• The library appears to only support square sprites.
• Sprites and animation frames are anchored at their center. Anchors should be user-definable.
• The draw function does not support rotation or scaling of sprites.
• Should animation timing be handled by Sprite? If so, how?

Design-Phase Considerations

• How should anchor points be specified?
• What are the current parameters for the sprite library? What is missing?
• Can the sprite code be simplified?

Coding-Phase Deliverables

• Modify the sprite library to support these fixes.
• Document the library in a docs/Sprite.md file. Walk developers through how to create a sprite with animations, and how to designate anchor points.
• Port town-adventure to use the sprite library.
• Create a sprite test project, which demonstrates all the features of the library. This example project should live in its own repository.

Group C: Tilemap Library

Sald's Tilemap Library is designed to help game developers draw grids of tiles. However, it could use some fixes and extensions.

• There is no documentation.
• A snippet similar to this should make sense: var map = new Tilemap(require('tiles.png'), require('level1.js'));. (Though it might require some extra parameters for tile size and shape.)
• Indexing should properly wrap when there are multiple rows of tiles.
• When drawing, tilemap should use the canvas's transform matrix to decide which tiles to draw.
• Make tilemap work with isometric grids (e.g. chesskoban, Civilization III).

Design-Phase Considerations

• What would it take to support isometric grids? Is it worth the added complexity?
• Recall our discussion of transformations from class and outline an algorithm to determine visible tiles from the current matrix.
• Can the tilemap code be simplified?

Coding-Phase Deliverables

• Modify the tilemap library to support these fixes.
• Document the library in a docs/Tilemap.md file. Walk a game developer through what they need to do to instantiate and use a Tilemap object.
• Port town-adventure to use the tilemap library.
• Create a tilemap test project, which demonstrates all the features of the tilemap library.

Group D: Benchmarking and Collision

We just finished an assignment to create a great collision library; but we've got a lot of versions of the code. Which one should we use?

• Build a SALD library to assist in benchmarking. It should make it easy to compute timings of a function over a varied set of inputs (generated by another function).
• One best practice for benchmarking is to use the minimum time over repeated runs.
• Read through the submitted collide.js and classify the approaches taken for each function. Among those implementations with good code quality, benchmark and select the fastest.

Design-Phase Considerations

• What function(s) should the benchmarking library export?
• What is your initial assessment of the collision code?
• What are the right test inputs for the collision functions?

Coding-Phase Deliverables

• Create a composite collide.js from the best components of the class's solutions as determined by correctness, speed, and clear code.
• Create and document a benchmarking library for SALD, "benchmark.js", documented in "Benchmark.md"
• Document how to use collide.js in a docs/collide.md file.
• Create an extensive testing program for collision, perhaps building on sald-collide-test or Andrew Sweet's slightly amended version.