Sims Tutorial

Sims-like game of a shoe salesperson described in the tutorial

The purpose of this tutorial is to help you create a Sims-style simulation of a shoe salesperson's day at work. You will need to define the salesperson's hierarchy of needs based on research and collaboration.

The finished simulation can be found in the Scalable Game Design Arcade here.

Design Process

The document created in order to properly plan for the creation of this simulation is located here.

How to Read This Tutorial

This Tutorial uses "collapsible boxes":

The Header Gives you the barebones information of what to do. To get a more in-depth explanation click the "show" button on the upper right side of this box
This section gives you more information on how to complete the tutorial step plus reasoning behind the code allowing for a better understanding of what you are doing. If you have any suggestions (Additions/Deletions/Changes/etc.) to any of these sections please email or tell one of the TA's or Teachers.

Getting Started

New Project: First, you should open a new project and give it a relevant name.  For this simulation, the project was named "Shoe Salesperson."  This tutorial was also created using 32 x 32 sized agents.

Agents: This project will require 7 agents to be created with some having multiple depictions.  These are shown below.

Salesperson	Customer	Register	Inventory	Wall	Floor	Bench

Worksheet:  The worksheet created for this simulation is shown below.  There are two rooms, one at the storefront where the customers will be, and a back room for storing inventory.

Programming diffusion for spreading the presence of targets

In order for the salesperson to know where to go to satisfy their needs, diffusion and hill climbing techniques will need to be used so that the salesperson can reach certain items in the store. Target agents that the salesperson will need to locate are the customer, the inventory shelves, and the register. To allow for the salesperson agent to track these items (using hill climbing), the floor agents will be used to diffuse the presence of the target agents.

Below is an image of how the diffusion may look when a Customer arrives to the store. Please note that this is just a visualization technique to show diffusion values, but the user will not see this while the simulation is running.

Here is the code necessary for each agent that will need to be located. This is the only code that will be located in the "While running" behavior of the agents.

Customer:

Register:

Inventory:

Floor:

The code to diffuse these "presence" values of the various target agents will be placed in the floor agents. The simple form of diffusing one such value is essentially the average of the values from the four neighbors:

Set value to 0.25 * ( value[left] + value[right] + value[up] + value[down] )

In this case c represents the value that the Customer is sending out, r represents the Register, and i represents the Inventory.

Programming the Salesperson

The Salesperson must constantly keep track of what needs to be done based on a hierarchy representing the priority of these tasks. This means that the Salesperson needs to keep track of how long it's been since the store has been cleaned, how long it's been since inventory was done, and also whether or not a customer needs to be helped.

All of the code for this will be located within the behavior of the Salesperson, but the only code that will be in the "While running" portion of the behavior will be the checking of time, moving, and completing a task. This code is shown below.

Here, the Salesperson first calls updateHierarchy, which is a method that increments the counters for tasks that will need to be completed after a certain period of time. These include cleaning the store and doing inventory.

See screenshot of Salesperson "updateHierarchy" method

Next, the Salesperson calls a method that will move in a direction that will allow them to complete a task. If there are no tasks to be completed at the time, the Salesperson will just move randomly.

See screenshot and explanation of Salesperson "move" method

This method takes into account the hierarchy from the planning document. If the variable register is equal to 1 then the Salesperson will only call the method toRegister and ignore all other tasks until register is changed to 0. This occurs only if a Customer has bought shoes. The variable register is set in another method that is explained later. If the variable customer is set to 1, then the Salesperson will only call the method toCustomer and ignore any need to do inventory or clean. The variable customer is set in another method. If the variable inventoryCount is greater than 50 then the variable inventory is set to 1 and the method toInventory is called. You may recall that inventoryCount is updated every second in the method updateHierarchy. When inventoryCount is greater than 50, it will ignore any need to clean. If the variable cleanCount is greater than 20 then the variable clean is set to 1, no method is called here because the Salesperson does not need to move to a specific place to clean. Just like inventoryCount, cleanCount is updated every second in the method updateHierarchy. The default case is the last rule for movement. If there there is no tasks that need to be completed, the Salesperson will just move randomly on the floor and will not appear to be holding anything. This method shows two possible ways to satisfy tasks in a simulation. One is when an agent appears a flag will be set (customer and register), and the other is after a certain period of time a task will need to be completed (inventory and clean)

The third method the Salesperson calls will be the satisfyHierarchy method.  This method will have the Salesperson work on completing a task if it has been reached.  This may include just cleaning wherever the Salesperson is standing, doing inventory, helping a Customer, or getting shoes from the Register if the Customer wants shoes.

See screenshot and explanation of Salesperson "satisfyHierarchy" method

This method will have the Salesperson satisfy any needs if their flag is set to 1 and they are in a position on the worksheet to do so. The first two rules have the Salesperson ring up shoes if a Customer has agreed to buy them.  The first rule actually completes the task, and the second rule causes the Salesperson to ignore all other rules until the shoes have been rung up.  If the second rule was not there, an error may occur where the Salesperson starts cleaning on their way to the register.  The following is a pseudo-code explanation of the two rules. If I am next to the Register AND the register variable is set to 1, then tell the Register its method sale and then set the register variable to 0. Else if the registeris set to 1, then ignore all other rules in this method. The next three rules deal with the Salesperson satisfying any Customer needs. The first rule gives bought shoes to the Customer, the second rule has the Salesperson initially help the Customer, and the third rule causes the Salesperson to ignore all other rules until the Customer has been helped.  The following is a pseudo-code explanation of the two rules. If I am next to a Customer and the customer variable is set to 1 and I am holding a shoe box (meaning the Customer has bought shoes), then have the Customer run its sold method and change back to my usual self (give the Customer the box) Else if I am next to a Customer and the customer variable is set to 1, then have the Customer run its help method. Else if the customer variable is set to 1, then ignore all other rules in this method. The next rule has the Salesperson take inventory if they are next to the Inventory agents.  The pseudo-code is as follows. If I am next to at least one Inventory agent and the inventory variable is set to 1, then change my depiction to my usual self and call my doInventory method. The final rule to run in the satisfyHierarchy method is to have the Salesperson clean if the clean variable is set to 1.  The pseudo-code is as follows. If the clean variable is set to 1, then call my doCleaning method. These rules have the Salesperson communicate with the other agents and has them process the information.  For example, when the Salesperson has the Customer run its help method the Customer decides if it will buy shoes or not.  This is how it would happen in real life and so this simulation tries to emulate that.

Customer and Register Methods

There are many methods that the Salesperson needs in order to serve a Customer.  Most of these involve properly simulating communication between the Bench/Customer Generator, the Customer, and the Register.

The first of these is the method that the Bench/Customer Generator broadcasts to the the Salesperson to tell it to make serving the Customer a priority. This can be done by having the method set the customer variable to 1. Basically, this would be the same as hearing a door beep when a Customer enters which triggers the Salesperson's need to help them.

See screenshot of Salesperson "serveCustomer" method
Pseudo-code: When called, set the customer variable to 1.

Another necessary method tells the Salesperson that the Customer is leaving. For this to have meaning to the Salesperson agent, a method must set the customer variable to 0.

See screenshot of Salesperson "customerLeaving" method
Pseudo-code: When called, set the customer variable to 0.

A third communication method that is used has the Salesperson handle a request by the Customer to buy shoes.

See screenshot of Salesperson "buy" method
Pseudo-code: When called, set the register variable to 1, the customer variable to 0, and change the depiction of the Salesperson agent to holding money.

The final method used where other agents are communicating with the Salesperson is the holdShoebox method. This method simply changes the depiction of the Salesperson to holding a shoebox and lets other rules handle the Salesperson's movement back to the customer.

See screenshot of Salesperson "holdShoebox" method
Pseudo-code: When called, change the Salesperson's depiction to holding a shoebox.

Inventory Method

The doInventory method is called when the Salesperson is next to any Inventory agents and enough time has passed that doing inventory is necessary for the Salesperson.  In this case, inventory needs to be done every 50 seconds.  Since the simulation doesn't require any communication between the Salesperson and the Inventory, this method only needs to keep track of how long inventory has been done, stop after 10 seconds, and reset the counter for the next time inventory needs to be completed.

See screenshot of Salesperson "doInventory" method

Pseudo-code: If the inventoryTimer variable has reached 10 (seconds) then set the inventory , inventoryCount , and inventoryTimer variables to 0. Else increment the inventoryTimer variable up 1 every second and move randomly on the floor. Note: Since this method will be called every second through methods called through the while running method of Salesperson, inventory will only be taken a total of 10 seconds at a time.

Cleaning Method

The cleaning method, like the inventory method, also doesn't require any communication to occur with the Salesperson agent.  So it is very similar in that it changes depiction, keeps track of how long cleaning has been done, stops cleaning after 10 seconds, and then resets the counter for the next time cleaning needs to be completed.

See screenshot of Salesperson "doCleaning" method

Pseudo-code: If the cleanTimer variable has reached 10 (seconds) then change my depiction back to my usual self and set the clean, cleanCount , and cleanTimer variables to 0. Else change my depiction to look like I'm cleaning, increment the cleanTimer variable up 1 every second, and move randomly on the floor. Note: Since this method will be called every second through methods called through the while running method of Salesperson, cleaning will only be done a total of 10 seconds at a time.

Moving Towards Tasks

The final set of methods that are needed for the Salesperson agent are methods that tell the Salesperson where to move to satisfy a task.  These methods are called from the move method and use the diffusion discussed earlier in the tutorial.

The code for each method checks which direction the values of either c, i, or r (depending on the task needed to be completed) of the floor is the strongest and then moves in that direction.  The general pseudo-code for this is as follows:

If variable[right]>variable[up] and variable[right]>variable[down] and variable[right]>variable[left] then move right.

If variable[left]>variable[up] and variable[left]>variable[right] and variable[left]>variable[down] then move left.

If variable[up]>variable[right] and variable[up]>variable[down] and variable[up]>variable[left] then move up.

If variable[down]>variable[right] and variable[down]>variable[up] and variable[down]>variable[left] then move down.

Portions of this code are shown below for each method: toCustomer, toRegister, and toInventory.

See screenshot of Salesperson "toCustomer" method

See screenshot of Salesperson "toRegister" method

See screenshot of Salesperson "toInventory" method

Note: The variables used here were set in the while running method for each agent.

Programming the Bench/Customer Generator

The purpose of the Bench agent is to randomly generate a Customer agent every 20 seconds with 50% probability.  This agent also broadcasts to the Salesperson that a Customer has been generated, just like a bell going off at the door to the store.

See screenshot of Bench "while running" method
Pseudo-code: If I am next to 0 Customers and once every 20 seconds with a 50% probability, make a new Customer to my left and tell the Salesperson to run its serveCustomer method.

Programming the Customer

Besides the while running method that sets the c variable and allows for the Salesperson to hill climb towards the Customer, there is a method that the has the customer respond to help and a method to respond to having shoes sold to them.  Examples of each with pseudo-code can be seen below.

See screenshot of Customer "while running" method

See screenshot of Customer "help" method
Pseudo-code: If given a 33% chance is true, then have the Salesperson to run its buy method, tell them I'm buying the shoes, and wait so the message can be seen. Else if I chose not to buy the shoes, then tell the Salesperson I'm not buying the shoes, wait a second so the message can be seen, have the Salesperson run its customerLeaving method, and erase myself.

See screenshot of Customer "sold" method
Pseudo-code: Have the Salesperson run its customerLeaving method, say Thanks, wait a second so the message can be seen, and erase myself. Note: This method is only run when the shoes are returned and is called by the Salesperson.  There is no "if" part of the method because it is always run in a certain case.

Programming the Register

The register only has one method besides the while running that sets the variable used for hill climbing.  This method is the sale method and it tells the Salesperson to hold a shoebox and return to the Customer to give it to them.  Examples of the methods are shown below.

See screenshot of Register "while running" method
Note: This was discussed earlier in the Diffusion section

See screenshot of Register "sale" method
Pseudo-code: Have the Salesperson hold a shoebox, tell the Salesperson to return to the Customer, say something that indicates the sale was made, and wait a second to let the message be seen.