# Build-a-Habitat

## Open the app
Double-click **index.html** in this folder. Keep all app files together, including habitat.png and organisms-atlas.png. It works without installation, internet, an account, or a server. Use a current Chrome, Edge, Firefox, or Safari browser. No student responses leave the browser; reloading clears the session.

## What students learn
Fourth graders investigate how water, light, temperature, food, and nutrient recycling connect organisms. They predict, change conditions, observe several years, explain causes, and revise an experiment. The wetland food web is plants → pond snails → ducks, with fungi and bacteria recycling nutrients. Real ducks eat other foods; this deliberately simplified model uses only snails as their prey.

Bars and icons show relative abundance, not exact counts. One added group represents a small starting population. Consumers respond to the previous year's food supply, so some effects take time. Habitat Health combines the presence of food-web roles, plant abundance, water stress, and annual population change; it is a classroom clue, not a scientific ecosystem score. Gentle difficulty slows changes. No randomness or scores reward clicking.

## A 20–30 minute lesson
1. **Notice (3 minutes):** Open the starting habitat together. Identify producers, herbivores, predators, and decomposers. Ask what each needs.
2. **Predict (4 minutes):** Students change just one condition, or choose one challenge. Choose or write a prediction and give a reason.
3. **Test and observe (5 minutes):** Select Run the Habitat. Review the year buttons after it finishes. Describe which population changed first and which changed later.
4. **Explain (5 minutes):** Read the brief explanations and complete “I changed… / This caused… / I think this happened because…”. Use the bars and earlier years as evidence. Surprising predictions are opportunities to investigate, not wrong answers.
5. **Revise (5–8 minutes):** Share the written explanation before changing controls. Reset, make one different change, and predict again. Compare the experiments aloud or record them on paper. Ask: “What would you change next?”

Each run begins with the groups and conditions currently selected, not the previous run's final populations. Changing controls clears the old prediction, results, and explanation fields so each experiment has its own prediction. Reset Habitat restores the teacher's saved starting settings and clears the challenge. It works during an animation, too.

## Exactly where to customize
- **In the app:** Open **Teacher Settings** near the bottom. Change the activity title, ecosystem name, organism names and availability, starting conditions, difficulty, challenge availability, and simulated years (3–8). Apply Teacher Settings starts a fresh habitat. These settings last until the page is reloaded.
- **Permanent classroom content:** Edit the clearly labeled **CLASSROOM CONFIGURATION** in **config.js**. `CLASSROOM_CONFIG` holds the title, ecosystem, years, difficulty, starting conditions, and organism list. Each organism needs a unique `id`, `name`, `role`, `emoji`, starting `groups` (0–6), and `enabled`. Keep roles as `plant`, `herbivore`, `predator`, or `decomposer`. The `ENVIRONMENT` and `CHALLENGES` arrays below it hold labels and descriptions.
- **Another ecosystem:** Change that configuration, replace **habitat.png**, and update its image description in **index.html**. Also revise species-specific explanations in **app.js** and the food-web assumptions and environmental responses in **simulation.js**. Changing a name alone does not make wetland relationships appropriate to a desert or ocean.
- **Model behavior:** **simulation.js** contains the pure, deterministic `HabitatModel.simulate` function and comments describing assumptions. Water reflects starting water, rainfall, and heat. Growth also depends on light and nutrients. Challenges apply in Year 1; drought rainfall recovers after Year 2, while its ecological effects can persist. The disappearing-plant challenge removes the first present plant species in the configured list.
- **Organism placement:** `HABITAT_VISUALS` at the bottom of **config.js** maps each organism ID to a sprite cell, a habitat zone, a size, and stable anchor points. The atlas is a 3-column, 2-row transparent PNG. The scene preserves the backdrop’s 3:2 ratio so these points stay on the same land or water at every screen size. Add a visual mapping for each new organism ID; unmapped organisms still appear in controls and population totals.
- **Appearance and layout:** **styles.css** controls color, type, responsive layout, and animation. Reduced-motion preferences are respected.
- **Interface and result language:** **app.js** controls input, playback, predictions, explanations, and teacher settings. **index.html** contains the page structure and reflection prompts.

## Limits worth discussing with students
This model omits migration, disease, seasons, age groups, alternate prey, and many other factors. A population at zero does not reappear by itself. The plant-loss challenge can therefore permanently remove a species. Empty habitats are valid experiments. Populations can increase and later decrease; use the timeline instead of only the final year. Explanations describe model relationships, not proof of a single real-world cause.

## Validation notes
The simulation and interface-controller checks passed, including all environmental controls, organism bounds, challenge choices, prediction requirements, year navigation, reset during playback, empty habitats, and teacher settings. The model was also checked across 200 condition combinations. Visual browser verification could not be completed because the available preview browser blocks local-file URLs. Browser layout and native control behavior still need a classroom-device check.

## Improved habitat illustrations
Ducks use a swimming illustration with submerged feet. Grasses are anchored to marsh banks, lilies to open water, and decomposer fungi to logs on land. Snails appear on submerged rocks in a labeled, magnified pond-bottom view. Only surface organisms bob gently; rooted plants and fungi remain still. Groups retain their positions as populations change.

The mushroom illustration represents visible decomposer fungi, not bacteria. Bacteria also occur in water and sediment and are not visible at this scale. The scene key makes this distinction. Snails graze on algae and other plant material; the model still combines plant food into one simplified producer resource.

Background reading: [Missouri Department of Conservation: pond snails](https://mdc.mo.gov/discover-nature/field-guide/lunged-aquatic-snails-pulmonate-pond-snails) and [National Park Service: decomposing fungi](https://www.nps.gov/muwo/learn/nature/decomposing-fungi.htm).

### Artwork generation
`organisms-atlas.png` was created with the built-in image-generation tool. Final prompt: “A transparent 1536×1024 sprite atlas, exactly 3 columns × 2 rows. Top row: rooted green marsh grass with muddy base; white water lily on a flat lily pad; mallard swimming low with feet and lower belly submerged and a small water ripple. Bottom row: freshwater pond snail on an algae-covered submerged stone; tan decomposer fungi growing on a decaying log; empty transparent cell. Isolated illustrations with clear gutters, paper-cut editorial nature style in teal, leaf green, and earth brown. No text, borders, emoji styling, or visible duck feet.”