For this second assignment you will start to build the basic structure to visualize your world in 2D and populate your world with entities, some of which move. Your initial solutions to creating and placing entities and supporting entity movement will be naive but not unreasonable.

In general, this assignment focuses on:

• introducing you to pygame, the library we will use to draw our worlds (base code provided)
• creating one gatherer randomly but reasonably placed in your world
• creating one generator randomly but reasonably placed in your world
• creating one resource reasonably placed in your world (relative to the generator in your world)
• representing all three entities locations in 2D via an occupancy grid (see the more detailed explanation below - you will use the base code provided, including functions to access the grid)
• creating a naive way for your gatherer to move towards the current resource (assume your gatherer is currently all knowing)
• visualizing the location of all three entities (and the updated location of the gatherer) using different colors on the grid

Learning objectives more generally include:

• exposure to pygame's drawing and update
• exposure to writing functions
• exposure to using a 2D grid to represent occupied regions of space in a world (via provided functions to access and set grid data)
• practice using a 2D spatial logic and simple math on a manhattan grid
• practice making objects
• practice updating variables in objects
• practice using boolean logic

Using pygame with Python 3 on the department machines requires a step of setup. To simplify this, a script has been provied. Type the following at the command-line (on, e.g., unix11).

~akeen/public/pygame_setup

Now, the next time that you login you should be able to import the pygame module into Python 3. You can verify this by opening the python3 interpreter and typing import pygame. This should work based on the common setup of user accounts; I say should because this setup has changed over the years. If you have any issues, please let us know.

Create a hw2 directory in which to develop your solution. Download the hw2.zip file.

You will develop your program solution in multiple files. For testing, you will primarily focus on visual testing - which you must document via the generation of specific test images.

You are provided with two files: A2_base.py, which you should read and understand but only mimimally need to modify, and occ_grid.py, which you will need to read and understand some parts of (but not modify). To complete the assignment, you must create your own python file A2_sol.py that must contain very specific functions.

You will also use your entities.py file from assignment 1.

Familiarize yourself with the base code

Read and understand A2_base.py and take a look at occ_grid.py. Some of the material in occ_grid.py is more advanced and should not worry you beyond understanding in general what the occupancy grid represents and how to get and set values in the grid using the provided functions set_cell and get_cell explained in greater detail below. Do try to be sure you have a sense of what each function in A2_base.py does (look for def).

In brief, the occupancy grid allows us represent 2D space with discrete cells that store a number to represent what is at that point in our 2D space. In other words, it is a matrix of numbers representing positions of entities or empty space in our world. For example the following figure shows a 4 by 4 occupancy grid with all open space except for one gatherer (represented by the number '1') in the second row and third column :

0	0	0	0
0	0	1	0
0	0	0	0
0	0	0	0

Please read the complete occupancy grid notes below, after you understand the other general tasks you will be solving with this assignment.

Create a solutions file A2_sol.py

This file will need to include the following functions (A2_base.py demonstrates some invocations of these functions):

- createEntities which takes in the grid as an argument.
This code should do as the name implies and create one of each entity, a gather, a generator and a resource, which are all returned from this function (as a tuple). See below for specific testing at this stage.

- placeEntities which takes in the grid and one of each of the entities (i.e., the parameters are the grid, a gatherer, a generator, and a resource)
This function should set the appropriate values for each entity in the grid, using the helper functions below.

- determineNewGathererPosition, which takes in the gatherer and target resource
This function should take in the current position of the gatherer and the desired position (represented by the desired resource) and then move the gatherer 'one step' closer to the resource.

- isValidPosition, which takes in the grid and a potential position
This function checks if the position is valid with respect to the grid constraints.

- updateEntities which takes in the grid and one each of the entities
This function should determine the new position of the gatherer, confirm the new position is allowable by the grid (using prior functions), and then update the position and grid accordingly.

In general, you should develop the above functions to create your entities and have the gatherer move towards the resource. Decompose that problem into the above sub-problems.

You might find it easiest to develop and test these functions one at a time. You can test/try them in the interpreter (independent of the A2_base.py code) or write unit tests (you will not submit the unit tests for this assignment).

Note that, although gathers will move naively, each team must carefully design and document their choice for how their gatherers move toward a resource. Some examples include moving in one direction first (i.e. my sub will move all the way in X before it adjusts its position in Y - alternatives include, for example, a mail carrier that alternately moves down/up then left/right, another type of gatherer might move in a circularly expanding path, etc. You will be able to modify your movement at a later date, but take the time now to code something reasonable for your world.

You must check to make sure your gatherer does not move off your 2D grid world.

For visual testing:

• In the createEntities function, create a gatherer with its initial position to (1, 1).
• Set the value in the grid to 1 using the set_cell function described below.
• When drawing, if the value of the current grid cell is 1 (you can query the grid with the get_cell function described below), color the grid element a representational color (of your gatherer).
• Save a screen shot for the following two test positions of (1, 1) and (59, 59). You may submit an image stored in any reasonable format (e.g., jpeg, gif, png). The first image should be in a file named position1 with the appropriate extension. The second image should be in a file named position2 with the appropriate extension.

You are required to hand in your confirmation of testing setting the initial position.

After you have tested setting the start position, modify your code to initialize the gatherers start position to be random (but reasonable - reasonable means, on the grid somewhere that makes sense in your world).

Now do the same thing for a generator (consider carefully what a reasonable position means).

Now create one resource is a resonable position, relative to your generator. (Position must be relative).

Note that for now we will be using a very simple 2D occupancy grid to represent which entities are where in our world. We will be discussing the grid in lecture, but, in general, the base code creates a data structure that will hold a number for each grid of our current 2D 'toy' world (we will make our worlds larger later). This grid allows you to access each grixel (grid element) by indexing with an X and a Y position in the range of (0, 59) (note, however, our pixel values range from 0-599 and you will need to get used to converting from pixel to grixel at some point). For now, we will represent unoccupied regions of your world with a 0 (occ_grid.EMPTY) and then each of your three other entities (gatherer, generator, and resource) likewise will have their own numeric representation (gatherer = 1 (occ_grid.GATHERER), generator = 2 (occ_grid.GENERATOR), resource = 3 (occ_grid.RESOURCE)).

In the occ_grid.py code provided - you are provided with functions to access the grid:

• def set_cell(grid, point, value): which will set the grid at position "point" to the value specified
• def get_cell(grid, point): which will return the current value in the grid at the position represented by "point"

For example get_cell(grid, entities.Point(5, 6)) returns the value 2, this means there is a generator in that grid element. As you write code to create each of your entities, you must likewise update the grid data structure to store the correct numeric value to represent which entity is in that grid element. Likewise, as soon as the gatherer starts moving, you need to update the occupancy map, however for this assignment, please leave the "trail" of occupied cells that your generator has passed through as 'occupied' by the gatherer to assist in visual debugging. For example, while running, at various times, your screen might look like the following three examples (if your gatherer moves like my sub does).

You must submit your solution on unix1.csc.calpoly.edu (or on unix2, unix3, or unix4) by 11:59pm on the due date.

• You will submit to the akeen user.

  At the prompt, type handin akeen x101hw2 A2_base.py A2_sol.py position1.* position2.* entities.py occ_grid.py

Note that you can resubmit your files as often as you'd like prior to the deadline. Each subsequent submission will replace files of the same name.

The grading breakdown for this assignment is as follows.

• Clean Execution: 10% — Program executes without run-time errors (and the submitted source demonstrates a legitimate attempt at a solution).

• Test Cases visualized: 10% — Evidenced by images submitted for specified tests

• Functionality: 80% — Required functionality has been implemented.