Instruction file imported from jacoblontoc/better-ecology (.github/instructions/Better Ecology.instructions.md). Copyright stays with the author.

Better Ecology - Coding Instructions

1. Project Architecture (Composition-Based)

Follow this exact file structure for expandability. Do not use deep inheritance; use Traits and Interactions.

Structure: ├── api/ // Interfaces and base classes for other mods to hook into │ ├── trait/ // Base ITrait interfaces │ └── interaction/ // Base IInteraction interfaces ├── core/ // The "Engine" (Phase 1 logic) │ ├── components/ // The actual Data Attachments (Energy, Sex, NPK) │ ├── seasons/ // Global season and weather logic │ └── systems/ // Global calculators (The Director AI, Runoff Math) ├── content/ // YOUR SPECIFIC ORGANIZATIONS │ ├── organisms/ │ │ ├── animals/ │ │ │ ├── base/ // Base animal entity classes │ │ │ └── fox/ │ │ │ ├── FoxEntity.java │ │ │ ├── traits/ // HibernationTrait, ScavengerTrait │ │ │ └── interactions/ // DigFoxholeInteraction, HuntRabbitInteraction │ │ └── plants/ │ │ ├── base/ // Base plant/tree logic │ │ └── oak/ │ │ ├── OakTreeLogic.java │ │ ├── traits/ // HighNitrogenTrait, CanopyTrait │ │ └── interactions/ // DropLeafLitterInteraction, RootsBreakStoneInteraction │ └── blocks/ │ ├── soil/ │ │ ├── SoilBlock.java │ │ ├── traits/ // NPKContainerTrait, MoistureTrait │ │ └── interactions/ // NutrientsLeachInteraction │ └── carcass/ │ ├── CarcassBlock.java │ └── interactions/ // RottingInteraction, AttractScavengerInteraction ├── client/ // Rendering, Models, and Particles (Phase 2 visuals) └── registry/ // Where you tell Minecraft "This block exists"

2. Naming Conventions and Style

• Member Variables: Use the m_ prefix (e.g., private float m_energyLevel).
• Methods: Use standard camelCase.
• Documentation: Every class and public method must have a detailed Javadoc explanation.
• Safety: Use @Nullable and @Nonnull annotations consistently. Perform null checks on all registry lookups.

3. Data-Driven Logic (JSON Priority)

• All ecological constants (growth rates, scent potency, consumption rates, age limits) must be loaded from JSON configuration files.
• Use a central Configuration Manager to allow real-time adjustments without recompilation.

4. Biological Systems Logic

• Values: Energy, Stress, Nitrogen, Phosphorus, Potassium, Moisture are all floats [0.0 - 100.0].
• Time Continuity: For systems like decomposition or aging, use timestamps (World Time). Upon chunk reload, calculate the delta between currentTime and lastUpdate to "catch up" the state (e.g., Fresh Carcass -> Skeletal Carcass).
• Entity AI: Use AzureLib for animations. Prioritize POI (Point of Interest) coordinates for "Home" behaviors.

5. Visual Constraints

• Texture Density: Strictly 16x16.
• Geometry: Use Minecraft-native shapes.
  • "Slim" logs should use Fence geometry.
  • "Chunky" logs should use Wall geometry.
• No curves or smaller-than-pixel sub-models.

6. Soil and Block Logic

• Soil blocks must store NPK/Moisture data using Data Components.
• Implement "Nutrient Runoff" logic where gravity pulls NPK values from higher Y-levels to lower Y-levels during rain events.

7. Interaction Logic

• Traits: Data-only components (e.g., Sex, GeneticPotential).
• Interactions: Action-based components (e.g., HuntInteraction, GrazingInteraction).
• Predators: Pathfind based on "Scent" values. Scent potency of a Carcass must increase over time via JSON-defined curves.