Init

content/gameplay-systems/farming.en.md

@@ -0,0 +1,200 @@
+---
+title: Farming
+type: docs
+weight: 2
+---
+
+The farming system provides crop growth, harvesting, and animal coop mechanics.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.farming`
+
+## Architecture
+
+```
+FarmingPlugin
+├── Block Components (ChunkStore)
+│   ├── TilledSoilBlock - Farmland state
+│   ├── FarmingBlock - Crop growth tracking
+│   ├── FarmingBlockState - Block growth state
+│   └── CoopBlock - Animal coop state
+├── Entity Components (EntityStore)
+│   └── CoopResidentComponent - Animals in coops
+├── Growth Modifiers
+│   ├── FertilizerGrowthModifier
+│   ├── WaterGrowthModifier
+│   └── LightLevelGrowthModifier
+└── Farming Stages
+    ├── BlockTypeFarmingStageData
+    ├── BlockStateFarmingStageData
+    ├── PrefabFarmingStageData
+    └── SpreadFarmingStageData
+```
+
+## Block Components
+
+### TilledSoilBlock
+
+Tracks tilled soil state on ChunkStore:
+
+```java
+ComponentType<ChunkStore, TilledSoilBlock> type =
+    FarmingPlugin.get().getTiledSoilBlockComponentType();
+```
+
+### FarmingBlock
+
+Tracks crop growth progress:
+
+```java
+public class FarmingBlock {
+    // Growth rate modifier (0 = no spread on newly generated)
+    public void setSpreadRate(float rate);
+}
+```
+
+### FarmingBlockState
+
+Current farming state for a block position.
+
+### CoopBlock
+
+Animal coop block state for housing creatures.
+
+## Growth Modifiers
+
+Growth modifiers affect crop growth rate:
+
+| Modifier | Type ID | Description |
+|----------|---------|-------------|
+| `FertilizerGrowthModifierAsset` | `Fertilizer` | Boosts growth with fertilizer |
+| `WaterGrowthModifierAsset` | `Water` | Water proximity bonus |
+| `LightLevelGrowthModifierAsset` | `LightLevel` | Light-based growth |
+
+### Asset Configuration
+
+```yaml
+# Farming/Modifiers/bone_meal.json
+{
+  "Id": "bone_meal",
+  "Type": "Fertilizer",
+  "GrowthMultiplier": 2.0
+}
+```
+
+## Farming Stages
+
+Crops progress through stages defined as assets:
+
+| Stage Type | Type ID | Description |
+|------------|---------|-------------|
+| `BlockTypeFarmingStageData` | `BlockType` | Changes block type |
+| `BlockStateFarmingStageData` | `BlockState` | Changes block state |
+| `PrefabFarmingStageData` | `Prefab` | Places a prefab structure |
+| `SpreadFarmingStageData` | `Spread` | Spreads to adjacent blocks |
+
+### Spread Growth Behavior
+
+```java
+public interface SpreadGrowthBehaviour {
+    // Directional growth (vines, etc.)
+}
+
+public class DirectionalGrowthBehaviour implements SpreadGrowthBehaviour {
+    // Grows in specified direction
+}
+```
+
+## Interactions
+
+Registered farming interactions:
+
+| Interaction | Type ID | Description |
+|-------------|---------|-------------|
+| `HarvestCropInteraction` | `HarvestCrop` | Harvest mature crops |
+| `FertilizeSoilInteraction` | `FertilizeSoil` | Apply fertilizer |
+| `ChangeFarmingStageInteraction` | `ChangeFarmingStage` | Force stage change |
+| `UseWateringCanInteraction` | `UseWateringCan` | Water crops |
+| `UseCoopInteraction` | `UseCoop` | Interact with animal coop |
+| `UseCaptureCrateInteraction` | `UseCaptureCrate` | Capture animals |
+
+### Interaction Example
+
+```yaml
+# Item interaction definition
+{
+  "Type": "HarvestCrop",
+  "DropTable": "wheat_drops"
+}
+```
+
+## Animal Coops
+
+### FarmingCoopAsset
+
+Define coop configurations:
+
+```yaml
+# Farming/Coops/chicken_coop.json
+{
+  "Id": "chicken_coop",
+  "Capacity": 4,
+  "NPCGroups": ["chickens"],
+  "Drops": "egg_drops"
+}
+```
+
+### CoopResidentComponent
+
+Entity component for animals living in coops:
+
+```java
+ComponentType<EntityStore, CoopResidentComponent> type =
+    FarmingPlugin.get().getCoopResidentComponentType();
+```
+
+## Systems
+
+The farming plugin registers these ECS systems:
+
+| System | Description |
+|--------|-------------|
+| `OnSoilAdded` | Initialize soil when tilled |
+| `OnFarmBlockAdded` | Initialize crop when planted |
+| `Ticking` | Process growth each tick |
+| `MigrateFarming` | Migration for old data |
+| `OnCoopAdded` | Initialize coop blocks |
+| `CoopResidentEntitySystem` | Manage coop residents |
+| `CoopResidentTicking` | Coop production ticking |
+
+## Events
+
+```java
+// Prevent spread on newly generated chunks
+getEventRegistry().registerGlobal(
+    EventPriority.LAST,
+    ChunkPreLoadProcessEvent.class,
+    FarmingPlugin::preventSpreadOnNew
+);
+```
+
+## API Usage
+
+```java
+FarmingPlugin farming = FarmingPlugin.get();
+
+// Get component types for queries
+ComponentType<ChunkStore, FarmingBlock> farmingType =
+    farming.getFarmingBlockComponentType();
+
+// Check farming state
+FarmingBlock block = holder.getComponent(farmingType);
+if (block != null) {
+    block.setSpreadRate(1.0f);
+}
+```
+
+## Configuration
+
+Assets loaded from `Farming/` directory:
+- `Farming/Modifiers/` - Growth modifier definitions
+- `Farming/Coops/` - Animal coop definitions