If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wave-harmonic/crest shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 4d ago
• MIT licensed
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wave-harmonic/crest repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wave-harmonic/crest.

What it runs against: a local clone of wave-harmonic/crest — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wave-harmonic/crest | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wave-harmonic/crest. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wave-harmonic/crest.git
#   cd crest
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wave-harmonic/crest and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wave-harmonic/crest(\\.git)?\\b" \\
  && ok "origin remote is wave-harmonic/crest" \\
  || miss "origin remote is not wave-harmonic/crest (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/BoatAlignNormal.cs" \\
  && ok "crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/BoatAlignNormal.cs" \\
  || miss "missing critical file: crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/BoatAlignNormal.cs"
test -f "crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/RippleGenerator.cs" \\
  && ok "crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/RippleGenerator.cs" \\
  || miss "missing critical file: crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/RippleGenerator.cs"
test -f "crest/Assets/Crest/Crest-Examples/BoatDev/Materials/OpenOcean.mat" \\
  && ok "crest/Assets/Crest/Crest-Examples/BoatDev/Materials/OpenOcean.mat" \\
  || miss "missing critical file: crest/Assets/Crest/Crest-Examples/BoatDev/Materials/OpenOcean.mat"
test -f ".github/FUNDING.yml" \\
  && ok ".github/FUNDING.yml" \\
  || miss "missing critical file: .github/FUNDING.yml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wave-harmonic/crest"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Crest is a class-leading water simulation system for Unity's built-in renderer that procedurally generates ocean surfaces with dynamic wave physics, foam, and buoyancy interactions. It combines shader-based wave animation (HLSL/ShaderLab, 124KB and 163KB respectively) with C# runtime systems to enable boats and objects to interact realistically with water surfaces in real-time. Monolithic Unity project structure: crest/Assets/Crest/ contains the core water system, Crest-Examples/BoatDev/ contains boat interaction prefabs and example materials (DynWavesAddBump.mat, WaterInteractionBoatProbes.mat, etc.). Materials reference shaders for wave displacement, foam, and buoyancy calculations; C# runtime coordinates sampling and physics integration.

Game developers using Unity's built-in renderer who need production-grade water for open-world games, maritime simulations, or water-based gameplay—particularly those shipping titles like FAR: Changing Tides, Windbound, and Wavetale. Technical artists and gameplay programmers implementing boat physics, water interaction probes, and procedural wave displacement.

Production-ready and actively maintained. The project has shipped in multiple commercial titles, maintains comprehensive documentation via ReadTheDocs, has dedicated Discord community (discord.gg/JJjx9qcq83), and offers support through Unity Asset Store and GitHub sponsorship. Crest Water 5 is now available, indicating ongoing evolution while this branch (Crest Water 4) receives stability focus.

Low risk for production use but limited to built-in renderer—separate forks required for HDRP and URP pipelines (asset store SKUs 252194, 164158, 141674). Single GitHub organization (wave-harmonic) maintains the primary repos. Code is heavily shader-dependent (287KB of HLSL/ShaderLab), making GPU driver compatibility a consideration. No visible CI/test suite in the file list suggests manual QA reliance.

The repo is in maintenance mode for Crest Water 4 with Crest Water 5 now available on Asset Store. CONTRIBUTING.md and GitHub issue templates (bug.yml, feature.yml, config.yml) suggest active community contributions. BoatDev examples demonstrate ongoing refinement of water-boat interaction mechanics (AlignNormal, Probes, Wakes).

Clone the repository: git clone https://github.com/wave-harmonic/crest.git. Open crest/ folder in Unity (2019 LTS or later, built-in renderer). Load a scene from crest/Assets/Crest/Crest-Examples/BoatDev/ and press Play. No external dependencies or build steps—pure Unity project.

Daily commands: In Unity Editor: open crest/ project, navigate to Assets/Crest/Crest-Examples/BoatDev/, load any scene (e.g., containing OceanLiner.prefab), press Play. Water renders in viewport with interactive boat physics. No command-line runtime—purely editor-based development.

• crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/BoatAlignNormal.cs — Core boat physics interaction with water—demonstrates how dynamic objects integrate with the Crest water simulation system.
• crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/RippleGenerator.cs — Example water disturbance logic; critical for understanding how external forces feed into the wave simulation.
• crest/Assets/Crest/Crest-Examples/BoatDev/Materials/OpenOcean.mat — Base water shader material; defines the visual and computational foundation for ocean rendering.
• .github/FUNDING.yml — Sponsorship configuration; essential for understanding project maintenance and support model.
• CONTRIBUTING.md — Contribution guidelines and expectations; required reading before submitting any pull requests.
• README.md — Project overview, feature summary, and platform support matrix; entry point for all developers.
• .readthedocs.yaml — Documentation build configuration; critical for understanding how to generate and publish docs.

Add a new boat with water interaction

1. Create a new boat prefab in BoatDev/Data/ directory, inheriting from existing boat models (crest/Assets/Crest/Crest-Examples/BoatDev/Data/OceanLiner.prefab)
2. Attach BoatAlignNormal script component to align boat with water surface (crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/BoatAlignNormal.cs)
3. Create water interaction material in BoatDev/Materials/ for wake generation (crest/Assets/Crest/Crest-Examples/BoatDev/Materials/WaterInteractionBoatProbes.mat)
4. Add RippleGenerator script to create wave disturbances from boat movement (crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/RippleGenerator.cs)
5. Reference the boat in an example scene and configure in BoatDev/Settings/ (crest/Assets/Crest/Crest-Examples/BoatDev/Scenes/boat.unity)

Customize water appearance and behavior

1. Duplicate OpenOcean.mat to create a new water material variant (crest/Assets/Crest/Crest-Examples/BoatDev/Materials/OpenOcean.mat)
2. Modify wave parameters in WavesBoatWakes.asset for amplitude, frequency, and direction (crest/Assets/Crest/Crest-Examples/BoatDev/Data/WavesBoatWakes.asset)
3. Adjust foam and wake settings in SettingsFoamWakes.asset for visual intensity (crest/Assets/Crest/Crest-Examples/BoatDev/Settings/SettingsFoamWakes.asset)
4. Apply the new material to water geometry in your scene (crest/Assets/Crest/Crest-Examples/BoatDev/Scenes/BoatWakes.unity)

Create a new example scene

1. Copy an existing scene prefab from BoatDev/Scenes/Internal/ (crest/Assets/Crest/Crest-Examples/BoatDev/Scenes/Internal/BoatWakesSceneCore.prefab)
2. Create a new Unity scene file in BoatDev/Scenes/ (crest/Assets/Crest/Crest-Examples/BoatDev/Scenes/BoatWakes.unity)
3. Instantiate the scene core prefab and customize with boats and water settings (crest/Assets/Crest/Crest-Examples/BoatDev/Scenes/Internal/BoatSceneCore.prefab)
4. Add LerpCam script for smooth camera transitions between viewpoints (crest/Assets/Crest/Crest-Examples/BoatDev/Scripts/LerpCam.cs)

• Unity Engine (Built-in Render Pipeline) — Cross-platform game engine with native water rendering, physics integration, and asset pipeline. Built-in renderer provides baseline compatibility before specialized render pipelines.
• Shader-based Wave Simulation — GPU-accelerated water surface deformation; materials and shaders allow real-time wave propagation, displacement, and interaction without heavy CPU overhead.
• Prefab System — Reusable, composable scene templates and boat configurations enable rapid iteration and multi-scene setup without code duplication.
• ScriptableObject Assets (Settings, Waves, Configs) — Data-driven configuration decouples behavior tuning from code; enables non-programmer artists to adjust parameters and iterate on visual effects.

• Built-in Render Pipeline as primary target; separate asset store packages for HDRP/URP

  • Why: Built-in is most widely compatible; splitting into separate products avoids shader/feature drift and allows specialized optimization per pipeline.
  • Consequence: Developers must choose correct package version upfront; cannot easily switch between pipelines post-import without re-purchasing asset.

• GPU-driven wave simulation via materials and shaders

  • Why: Scales to large water surfaces and multiple boats without CPU bottleneck; visual fidelity matches expectations.
  • Consequence: Limited real-time CPU-side queries of wave state; physics engines must approximate or use probe-based polling rather than analytical queries.

• Example scenes use prefabs and internal scene structure

  • Why: Modular scene assembly; allows quick remixing of boats, settings, and configurations for different showcase scenarios.
  • Consequence: Complexity in scene hierarchy; developers must understand prefab nesting and override patterns to customize effectively.

• Does not target mobile platforms (GPU compute and shader complexity require desktop-class hardware).
• Does not implement fluid simulation from first principles (uses wave-based approximation, not full Navier–Stokes).
• Does not provide networking/multiplayer synchronization for water state.
• Does not include built-in third-person controller or gameplay mechanics (focus is water system only).

No global project settings file (ProjectSettings/) visible in file list; Unity version compatibility must be inferred from README. Shader path references assume specific folder structure in Assets/Crest/—moving shaders breaks material references. BoatDev examples use prefab-based setup with baked material references; cloning prefabs requires rebinding shader materials. ReadTheDocs build configured in .readthedocs.yaml suggests documentation may lag code updates.

• Gerstner Waves (Trochoidal Waves) — Core algorithm Crest uses for procedural ocean surface generation; understanding wave superposition and frequency/amplitude tradeoffs is essential for tuning WavesBoatWakes.asset parameters and creating believable ocean motion.
• Displacement Mapping (Vertex Displacement via Texture Lookup) — Crest's shaders displace water mesh vertices using height textures sampled in real-time; this technique balances performance and detail fidelity and is central to understanding shader modifications in Materials/.
• Buoyancy Probes (Point-Sampling for Physics Integration) — BoatProbes.prefab uses multiple probe points to sample water height and compute torque/lift forces; this pattern avoids expensive per-vertex physics calculations and is the primary mechanism for boat-water interaction.
• Screen-Space Ambient Occlusion (SSAO) and Foam Rendering — Crest likely uses SSAO and procedural foam layers (visible in material names like DynWavesAddBump.mat) to add visual complexity; understanding these post-processing techniques helps customize water appearance.
• Render Texture and Ping-Pong Buffering — Wave simulation may use compute shaders or material-based simulation with ping-pong render targets to accumulate dynamic wave contributions; this pattern is essential for extending Crest with custom dynamic effects.
• GPU Instancing and Material Property Blocks — Efficient rendering of repeated water geometry and boat wake geometry across the ocean surface; likely used to reduce draw calls even with many interactive elements.
• Normal Map Blending and Fresnel Effect — Water appearance depends on layered normal maps (wave normals at multiple scales) and Fresnel-based reflection/refraction blending; modifying these in shaders creates stylistic variations while maintaining physical plausibility.

• reality/RealityShaders — Alternative water shader system for Unity; useful for comparing wave displacement techniques and foam rendering approaches.
• unity-technologies/Graphics — Official Unity rendering samples; provides context on built-in renderer constraints and shader best practices Crest adheres to.
• wave-harmonic/crest-examples — Likely companion repo containing extended examples and community-contributed boat/water scenarios for Crest integration.
• threedee/water-physics — Educational water physics simulation; offers reference implementations for buoyancy and hydrodynamic calculations if extending Crest's interaction model.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive boat physics integration tests for BoatDev example scenes

The BoatDev example folder contains multiple boat prefabs (BoatAlignNormal, BoatProbes, OceanLiner, ferryhumikablend) with complex water interaction materials, but there are no visible automated tests validating that boat physics behavior remains correct across updates. New contributors could add PlayMode tests that verify boat buoyancy, wake generation, and alignment with water surface normals.

• [ ] Create new test file: crest/Assets/Crest/Tests/PlayMode/BoatPhysicsTests.cs
• [ ] Add tests that instantiate BoatDev/Data prefabs and verify they float correctly on generated waves
• [ ] Add tests validating WaterInteraction materials apply correct forces from wave height sampling
• [ ] Document test setup in CONTRIBUTING.md with instructions for running BoatDev validation tests

Create GitHub Actions workflow for validating Crest example scenes load without errors

The repo has multiple Crest-Examples scenes (BoatWakes.unity and others) but no CI workflow ensures these example scenes remain loadable and functional after code changes. This prevents regressions where API changes break example content that new users rely on for learning.

• [ ] Create .github/workflows/validate-example-scenes.yml workflow file
• [ ] Add step that opens each .unity scene file in crest/Assets/Crest/Crest-Examples//Scenes/.unity and validates no console errors occur in headless mode
• [ ] Include validation of all material references in BoatDev/Materials still resolve correctly
• [ ] Document workflow trigger strategy (on-push to main, PR) in CONTRIBUTING.md

Add material configuration documentation and validation utilities for water interaction shaders

The BoatDev folder contains 8 water interaction materials (AddBumpsToWater.mat, DynWavesAddBump.mat, PushWaterBelowSphere.mat, etc.) with unclear configuration requirements. New contributors could document the shader parameters and create a validation script that helps users correctly configure these materials for their use case.

• [ ] Create documentation file: docs/water-interaction-materials.md detailing each material's purpose and required shader properties
• [ ] Add utility script: crest/Assets/Crest/Scripts/WaterInteractionMaterialValidator.cs that inspects assigned materials and warns about missing/misconfigured shader parameters
• [ ] Create a README in crest/Assets/Crest/Crest-Examples/BoatDev/Materials/ explaining the material naming convention and typical use cases
• [ ] Reference this new documentation from CONTRIBUTING.md in a 'Material Configuration' section

• Add unit tests for C# water sampling logic (WaveDataFetcher or equivalent)—currently no test suite visible in file structure; start by creating Assets/Crest/Tests/ and unit testing height lookup at specific coordinates.
• Document shader parameters in WaterInteractionBoatProbes.mat and DynWavesAddBump.mat by adding tooltip comments in shader code and syncing with ReadTheDocs shader reference—currently no shader parameter guide in visible files.
• Create a simplified 'minimal boat' prefab in Crest-Examples/BoatDev/Data/ (lighter than OceanLiner) for new users; include comments explaining each component (mesh, rigidbody, water interaction script, probe positions).

The Crest water system repository demonstrates a relatively secure posture for a Unity-based game engine project. No critical vulnerabilities were identified in the visible file structure. The codebase contains primarily asset files, configuration files, and example scenes with no exposed hardcoded secrets, SQL injection risks, or obvious misconfigurations detected. Main concerns are: (1) lack of visible dependency management files for security auditing, (2) third-party asset sourcing without visible verification mechanisms, and (3) absence of a formal security policy. The project is open-source and community-driven, which generally aids security through transparency. For production use, implement dependency tracking, asset verification processes, and establish a formal security reporting channel.

• Low · Limited visibility into dependency security — Project root / dependency management. The analysis was performed on a Unity game engine project with no package dependency file (package.json, packages.config, or similar) provided. This makes it impossible to assess whether the project uses vulnerable third-party libraries or dependencies with known CVEs. Fix: Maintain and regularly audit dependency files (if applicable). For Unity projects, regularly check asset store packages and imported plugins for security updates. Use Software Composition Analysis (SCA) tools to track dependencies.
• Low · Third-party model asset sourcing — crest/Assets/Crest/Crest-Examples/BoatDev/Models/ferryhumika/. The project includes third-party 3D models (ferryhumika.fbx) with a SOURCE.txt file reference. External asset sources may not be verified for security, and importing untrusted models could introduce risks. Fix: Verify the integrity and source of all third-party assets. Document the origin of imported models and maintain a Software Bill of Materials (SBOM). Only use assets from trusted sources.
• Low · No visible security policy or vulnerability disclosure — Repository root. While a CONTRIBUTING.md exists, there is no visible SECURITY.md file or vulnerability disclosure policy in the repository structure, making it unclear how security issues should be reported. Fix: Create a SECURITY.md file following best practices (e.g., https://securitypolicy.dev/) to define how security vulnerabilities should be reported privately and responsibly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.