CompSci 308 : Spring 2025

Cell Society: Functional Change Specifications

The additional requirements below are intended to emphasize the Cell Society Design Specification by challenging assumptions you may have made in your Basic version.

Below is a table of the project’s expected functionality, following the format in the Functional Requirements Glossary (which describes the difference between Core, Variation, and Extension requirements). You are expected to implement all Core requirements, but only enough Variation and Extension requirements of your choice to validate you are making good choices to meet the Design Specifications.

A program with fewer features, refactored to clearly demonstrate your design supports extension through abstractions, is worth more than a program with more, poorly designed features that expose implementation details, add special case conditionals, hardcode values, or otherwise diminish the rest of your design efforts.

Simulations

Implement additional CA Simulation variations.

ID	Name	Priority	Description
`CELL-26A`	Simulation: General Game of Life	Variation[6]	Extend the Game of Life simulation to take a rulestring parameter that gives the number of neighbors that cause a live cell to survive and a dead cell to be born. You should support at least the B/S and S/B variations given in this description. For example, the rulestring "B3/S12345" generates patterns that look like mazes. Consider using Java's Regular Expressions to elegantly parse the different rulestring format variations. You must write at least 3 different configuration files that run successfully to test this simulation.
`CELL-26B`	Simulation: Falling Sand/Water	Variation[6]	A simulation that mimics granular materials like sand or water. Particles fall, interact, and form structures under simulated gravity. See this assignment for states and state-transition rules (and in video). You must write at least 3 different configuration files that run successfully to test this simulation.
`CELL-26C`	Simulation: Rock Paper Scissors	Variation[6]	A simulation that models competing bacteria colonies. This lesson or this article or this video provide simplified rules that will clarify how to implement a general version (i.e., any number of states) such that each state is "beaten" by the next one in a circle (modulus). Thus the parameters for this simulation are number of states and percentage of neighbors needed to beat the cell. You must write at least 3 different configuration files that run successfully to test this simulation.
`CELL-26D`	Simulation: Foraging Ants	Variation[6]	A simulation that models the behavior of ants foraging for food by leaving pheromones, finding food, and returning to the nest. See this paper (rules start at the bottom of page 2) for states and state-transition rules (and in video). You must write at least 3 different configuration files that run successfully to test this simulation.
`CELL-26E`	Simulation: Langton’s Loop	Variation[6]	A self-replicating automaton, Langton’s Loop demonstrates patterns that can create copies of themselves. See this table or Wikipedia for states and state-transition rules (and in video). Try a pre-1994 model and a post-1994 model, no more than 3 count towards your 6 variations. You must write at least 3 different configuration files that run successfully to test this simulation.
`CELL-26F`	Simulation: SugarScape	Variation[6]	SugarScape involves agents interacting in a virtual landscape, competing for resources like sugar. See this paper for states and state-transition rules (and in video). The models are described as "Presets", no more than 3 count towards your 6 variations. You must write at least 3 different configuration files that run successfully to test this simulation.

NOTE: several of these simulations require that the grid location itself contain a “patch of ground” that can also have state and rules in addition to a cell.

XML Configuration Error Handling

Implement error checking for incorrect file data. This table describes the minimal error handling you must implement (remember Design Requirements DESIGN-13 and DESIGN-14):

ID	Name	Priority	Description
`CELL-27`	Input Missing Parameters	Core	When the user loads a configuration file that has a missing simulation type, name, author, or description, the program should display an error message to the user indicating why the configuration is not valid. For simulation specific configuration values (i.e., `probCatch` for catching fire), the simulator should provide a reasonable default value rather than throwing an exception. For grid size, it may be possible to calculate from the initial states, if they are provided. It must throw an Exception to be caught in the appropriate View method(s). Include at least 1 simulation configuration file that demonstrate this error.
`CELL-28`	Invalid Value Check	Core	When the user loads a configuration file that has an invalid value (like a non-existent simulation, bad XML tag, or negative value), the program should display an error message to the user indicating why the configuration is not valid. It must throw an Exception to be caught in the appropriate View method(s). Include at least 1 simulation configuration file that demonstrate this error.
`CELL-29`	Invalid Cell State Check	Core	When the user loads a configuration file that has invalid cell state values, the program should display an error message to the user indicating why the configuration is not valid. It must throw an Exception to be caught in the appropriate View method(s). Include at least 1 simulation configuration file that demonstrate this error.
`CELL-30`	Grid Bounds Check	Core	When the user loads a configuration file that has cell locations specified outside the grid’s bounds, the program should display an error message to the user indicating why the configuration is not valid. It must throw an Exception to be caught in the appropriate View method(s). Include at least 1 simulation configuration file that demonstrate this error.
`CELL-31`	File Format Validation	Core	When the user loads a configuration file that has empty, badly formatted, or non-XML file, the program should display an error message to the user indicating why the configuration is not correctly formatted. It must throw an Exception to be caught in the appropriate View method(s). Include at least 1 simulation configuration file that demonstrate this error.

NOTE: provide at least 1 example configuration file for each additional error specifically checked for beyond these and document each in the project README file.

XML Configuration Initialization

In addition to providing all the initial cell state values, allow the starting configuration of the cell states to be set algorithmically:

ID	Name	Priority	Description
`CELL-32A`	Random Configuration by Total States	Variation[2]	Implement a new XML element in the configuration file to allow random assignment of cells to a specified *number* of states. When these values are set, the program should randomly assign cell states so that the number of cells of each state match the provided values (if EMPTY or DEAD cells are not included, they will fill out the remaining cells). For instance, a 4x4 Game of Life set to 6 `alive` cells would have 6 `alive` cells and 10 `dead` cells. Exact initial states should not be given in the XML in this case. Include at least 2 simulation configuration files to demonstrate this option.
`CELL-32B`	Random Configuration by Probability Distribution	Variation[2]	Implement a new XML element in the configuration file to allow random assignment of cells to a specified *proportion* of states. When these values are set, the program should randomly assign cell states so that the ratios between the states matches the provided values (if empty or dead cells are not included, they will fill out the remaining cells). For example, a 3x3 Game of Life with 66% `alive` cells would have 6 `alive` cells and 3 `dead` cells. Exact initial states should not be given in the XML in this case. Include at least 2 simulation configuration files to demonstrate this option.
`CELL-32C`	Pattern to Insert	Variation[2]	Implement a new XML element in the configuration file that specifies an initial configuration of the states for the cells in the grid that can be combined with other configurations. While this format enumerates exact state values like `CELL-07`, it uses a different element so that it can be used in the View (see `CELL-41`) to partially fill in Grid spaces starting at a given point in an existing Grid, not as a complete Grid state specification. Include at least 2 simulation configuration files to demonstrate this option.

NOTE: document the expected XML tag and/or attribute name(s) and formats in your README file.

Configuration Preferences

Implement file storage options to allow users to persist data between program runs:

ID	Name	Priority	Description
`CELL-33`	App Preferences	Core	Allow users to save and load default preferences (such as theme, language, colors, etc.) These values should be used unless overridden using the UI or specific simulation configuration values.
`CELL-34`	Simulation State	Extension	Allow users to save the exact state of the entire program (such as all running simulations, their current iteration, grid state, colors, etc.) This should allow the user to quit and then get right back to where they were easily.

NOTE: you can use either XML (general data storage) or Java's Properties (key-value pairs) file format to save this information.

Graphical User Interface

Implement UI elements to allow users to interact with simulations.

ID	Name	Priority	Description
`CELL-35`	Splash Screen	Core	When the program starts, provide a Splash Screen that: displays the program's name a mechanism to select a language (see `CELL-36`) and color theme (see `CELL-37`) a mechanism to start a new blank simulation from one of the implemented options, load the saved program state (see `CELL-34`), or an initial starting configuration (see `CELL-10`) any other information or configuration that you think will be helpful
`CELL-36`	Simulation Language Customization	Core	Allow customization of the language used for the UI text (e.g., English, Spanish, Emoji). Remember `DESIGN-15`. This may be configured once in the Splash Screen (see `CELL-35`) to avoid the complexity of dynamically resetting the text of every Node already created. Include at least 2 languages in addition to English.
`CELL-37`	Theme Selection	Core	Allow users to select from different UI themes, such as “dark mode” and “light mode” or “Duke mode” and “UNC mode”. Remember `DESIGN-15`. These themes can include multiple style changes, such as font sizes. Note: when the user changes the theme, the UI is immediately updated (since applying a new stylesheet has an immediate effect on all Nodes in the Scene.
`CELL-38`	Error Reporting	Core	Display errors in a user-friendly way rather than printing them to the console or crashing the program. The text for these messages should come from Resource Property files files so they can also be translated to multiple languages (see `CELL 36`).
`CELL-39`	Cell State Colors Customization	Core	Allow customization of the colors of cell states (e.g., empty cells as blue to represent a water world or black to represent a space world). These should be an option provided in the XML configuration file.
`CELL-40`	Multiple Simultaneous Simulations	Core	Allow users to run multiple simulations concurrently. Document UI decisions such as window arrangement and the independence of each simulation in the README
`CELL-41`	Insert Pattern	Extension	Allow users to select an Pattern (see `CELL-32C`) available for the current Simulation to insert into the current grid by clicking on a space, replacing the current state values for all the spaces it would cover.
`CELL-42`	Cell Shape Customization	Extension	Allow customization of the *appearance* of cells based on their state (e.g., circles, rectangles, or images like sharks or fire). This does not affect the structure of the grid, only the graphical presentation. These should be an option provided in the XML configuration file.
`CELL-43`	Step Simulation	Extension	Allow users to progress the simulation one iteration at a time both forward and backward. Each updated simulation state should be displayed to the user in the simulation view.
`CELL-44`	Help Documentation	Extension	Provide an HTML help view that lists the *currently available* simulations, with at least their description, rules, and an example. Note, this content must be included with the program, not simply a link to an existing web page. For this academic application, you can copy properly attributed content. Note, in a real application these would also be available in the user's chosen language but, to complete this requirement, you only need to translate the Simulation Name Title.

Dynamic Updates

Implement UI elements to allow users to interactively change simulation values while it is running such that each change takes immediate effect:

ID	Name	Priority	Description
`CELL-45A`	Dynamic Updates: Simulation Parameters	Variation[3]	Allow users to change the configuration parameters of a currently loaded simulation (i.e., sliders or text fields organized in a separate panel). Simulation parameters include things like `probCatch` from Spreading Fire. When a user changes a value, the simulation should immediately apply this change in computing the next generation. This requires a number of GUI components constructed based on the parameters required by the current simulation.
`CELL-45B`	Dynamic Updates: Grid States	Variation[3]	Allow users to manually alter a cell state of a currently loaded simulation (i.e., by clicking on the cell). When a user changes the state of a specific cell in the grid, the simulation should update in real-time to reflect this new state.
`CELL-45C`	Dynamic Updates: Grid Outline	Variation[3]	Allow users to toggle on/off cell outlines in the grid of a currently loaded simulation (i.e., a button or checkbox). When a user chooses to toggle the grid outline, the simulation should immediately apply this change, either displaying or hiding the grid lines.
`CELL-45D`	Dynamic Updates: Flip Grid	Variation[3]	Allow users to "flip" the grid (i.e., about the horizontal or vertical axes, and possibly other matrix operations you can think of). You can choose whether this is just a View status or also causes the Model to change its representation.
`CELL-45E`	Dynamic Updates: Cell Fading	Variation[3]	Allow users to determine how long to "fade" a cell (i.e., when it switches from one state to another take `N` iterations to transition it from one color to another). See this video or this video to see how this effect adds visual interest to a simulation. Note, this should not change the Model data just its display, although it will likely require extra state for each state to count up after each state switch.