Init

content/gameplay-systems/camera-effects.en.md

@@ -0,0 +1,191 @@
+---
+title: Camera Effects
+type: docs
+weight: 6
+---
+
+The camera system provides screen effects like camera shake and view bobbing.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.camera`
+
+## Architecture
+
+```
+CameraPlugin
+├── Effects
+│   ├── CameraShakeEffect - Screen shake effect
+│   └── CameraShake asset
+├── View Bobbing
+│   ├── ViewBobbing asset
+│   └── ViewBobbingPacketGenerator
+├── Interactions
+│   └── CameraShakeInteraction
+├── Systems
+│   └── CameraEffectSystem
+└── Commands
+    └── CameraEffectCommand
+```
+
+## Camera Shake
+
+### CameraShakeEffect
+
+Registered camera effect type:
+
+```java
+getCodecRegistry(CameraEffect.CODEC).register(
+    "CameraShake",
+    CameraShakeEffect.class,
+    CameraShakeEffect.CODEC
+);
+```
+
+### CameraShake Asset
+
+Camera shake definitions loaded from `Camera/CameraShake/`:
+
+```java
+HytaleAssetStore.builder(String.class, CameraShake.class, new IndexedAssetMap())
+    .loadsBefore(CameraEffect.class)
+    .setPath("Camera/CameraShake")
+    .setKeyFunction(CameraShake::getId)
+    .setReplaceOnRemove(CameraShake::new)
+    .setPacketGenerator(new CameraShakePacketGenerator())
+    .build();
+```
+
+### CameraShake Configuration
+
+```yaml
+# Camera/CameraShake/explosion.json
+{
+  "Id": "explosion",
+  "Intensity": 1.0,
+  "Duration": 0.5,
+  "Frequency": 10.0,
+  "FalloffDistance": 20.0
+}
+```
+
+## View Bobbing
+
+Camera movement during player locomotion:
+
+### ViewBobbing Asset
+
+```java
+HytaleAssetStore.builder(MovementType.class, ViewBobbing.class, new DefaultAssetMap())
+    .setPath("Camera/ViewBobbing")
+    .setKeyFunction(ViewBobbing::getId)
+    .setPacketGenerator(new ViewBobbingPacketGenerator())
+    .build();
+```
+
+Key indexed by `MovementType` enum for different movement states.
+
+### ViewBobbing Configuration
+
+```yaml
+# Camera/ViewBobbing/walking.json
+{
+  "Id": "WALKING",
+  "HorizontalAmplitude": 0.02,
+  "VerticalAmplitude": 0.01,
+  "Frequency": 2.0
+}
+```
+
+## Interactions
+
+### CameraShakeInteraction
+
+Trigger camera shake from interactions:
+
+```java
+getCodecRegistry(Interaction.CODEC).register(
+    "CameraShake",
+    CameraShakeInteraction.class,
+    CameraShakeInteraction.CODEC
+);
+```
+
+### Usage Example
+
+```yaml
+# Item or block interaction
+{
+  "Type": "CameraShake",
+  "ShakeId": "explosion",
+  "Intensity": 0.5
+}
+```
+
+## Systems
+
+### CameraEffectSystem
+
+ECS system for processing camera effects:
+
+```java
+getEntityStoreRegistry().registerSystem(new CameraEffectSystem());
+```
+
+## Commands
+
+### CameraEffectCommand
+
+Admin command for testing camera effects:
+
+```java
+getCommandRegistry().registerCommand(new CameraEffectCommand());
+```
+
+Usage:
+```
+/cameraeffect <effect_id> [intensity] [duration]
+```
+
+## API Usage
+
+### Applying Camera Shake
+
+```java
+// Through interaction system
+// Define in asset JSON and trigger via interaction
+
+// Or programmatically through CameraEffectSystem
+```
+
+### Getting Camera Assets
+
+```java
+// Get camera shake asset
+CameraShake shake = CameraShake.getAssetMap().getAsset("explosion");
+
+// Get view bobbing for movement type
+ViewBobbing bobbing = ViewBobbing.getAssetMap().getAsset(MovementType.WALKING);
+```
+
+## Packet Generation
+
+Both camera shake and view bobbing use packet generators for client sync:
+
+```java
+public class CameraShakePacketGenerator implements PacketGenerator<CameraShake> {
+    // Generates network packets for camera shake
+}
+
+public class ViewBobbingPacketGenerator implements PacketGenerator<ViewBobbing> {
+    // Generates network packets for view bobbing
+}
+```
+
+## Asset Dependencies
+
+Camera shake assets load before camera effects:
+
+```java
+.loadsBefore(CameraEffect.class)
+```
+
+This ensures shake definitions are available when camera effects reference them.