# Survivalcraft振动反馈模组

**Repository Path**: RegulusSource/Survivalcraft-Vibration-Mod

## Basic Information

- **Project Name**: Survivalcraft振动反馈模组
- **Description**: 为《生存战争插件版》（Survivalcraft API）提供基于 Android VibrationEffect 的波形振动反馈。模组在本地主玩家触发受伤、攻击、破坏方块等事件时，调用系统振动器产生可控波形与振幅的震动。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Survivalcraft Vibration Mod 振动反馈模组

为《生存战争插件版》（Survivalcraft API）提供基于 Android `VibrationEffect` 的波形振动反馈。模组在本地主玩家触发受伤、攻击、破坏方块等事件时，调用系统振动器产生可控波形与振幅的震动，而不是简单的时间-强度调用。

## 功能

- **波形振动**：通过反射调用 `Android.OS.VibrationEffect.CreateWaveform(long[] timings, int[] amplitudes, int repeat)`，支持多段时序与每段振幅控制；同时兼容旧版 Android 只有 `(long[], int[])` 两参数重载的情况。
- **内置事件**（均通过 `ModLoader` 钩子触发，无需 Harmony 补丁）：
  - `TakeDamage`：玩家受到伤害。
  - `AttackHit`：玩家近战攻击命中生物。
  - `BlockBroken`：玩家破坏方块。
  - `BlockPlaced`：玩家放置方块（默认关闭）。
  - `LowHealth`：低生命值警告（默认关闭，可由其他模组触发）。
  - `Death`：玩家死亡。
- **WhatLookMod 联动事件**：
  - `GazeWarning`：开始被注视。
  - `GazeActive`：注视加速已激活。
  - `GazeEnded`：注视结束、加速消失。
- **配置保存**：所有开关、全局强度、主玩家生效选项通过 `ModSettings.xml` 中的 `<Vibration>` 节点持久化。
- **弱耦合接口**：其他模组可通过反射调用 `VibrationManager.Trigger(string eventTypeName, float intensity)` 触发振动，无需引用本模组。

## 文件结构

```
SurvivalcraftVibrationMod/
├── SurvivalcraftVibrationMod/
│   ├── VibrationConfig.cs                   # 配置与默认振动模式
│   ├── VibrationEventType.cs                # 标准事件枚举
│   ├── VibrationManager.cs                  # 反射振动核心
│   ├── VibrationModLoader.cs                # ModLoader 入口与事件钩子
│   ├── VibrationPattern.cs                  # 波形描述
│   ├── modinfo.json                         # 模组元数据
│   └── SurvivalcraftVibrationMod.csproj     # 项目文件
└── README.md
```

## 安装

1. 构建项目：
   ```bash
   dotnet build SurvivalcraftVibrationMod/SurvivalcraftVibrationMod.csproj -c Release
   ```
2. 将生成的 `SurvivalcraftVibrationMod.scmod` 复制到游戏 `Mods` 目录。
3. 与 `WhatLookMod`（或其他支持振动事件的模组）一起启用。

### 条件编译（联机支持）

本模组对联机相关代码（`OnNetworkHealthInjured`、`OnNetworkCreatureDied`、`OnNetworkPlayerHit` 等钩子）使用 `MULTIPLAYER` 符号条件编译：

- **默认（不定义 `MULTIPLAYER`）**：对应不含联机代码的 API（如 `SCAPI1.9` 分支），联机钩子不编译，仅保留 `OnBlockDug`/`OnPlayerInputInteract`/`OnPlayerInputHit` 等通用钩子。构建命令：
  ```bash
  dotnet build -c Release
  ```
- **启用联机支持**：当引用的 API 含联机代码（`NetworkManager`、`OnNetwork*` 钩子存在）时，传入属性启用：
  ```bash
  dotnet build -c Release -p:MultiplyerEnabled=true
  ```
  或在 `.csproj` 中将 `<DefineConstants Condition=" '$(MultiplyerEnabled)' == 'true' ">` 改为无条件定义。

> 未启用联机支持时，受伤/死亡振动（依赖 `OnNetwork*` 钩子）不会触发；攻击命中、破坏/放置方块振动正常。

## 配置

配置文件保存在游戏存档/设置目录的 `ModSettings.xml` 中，节点名 `<Vibration>`：

```xml
<Vibration>
  <Enabled>true</Enabled>
  <GlobalIntensity>1</GlobalIntensity>
  <AffectMainPlayer>true</AffectMainPlayer>
  <EnableTakeDamage>true</EnableTakeDamage>
  <EnableAttackHit>true</EnableAttackHit>
  <EnableBlockBroken>true</EnableBlockBroken>
  <EnableBlockPlaced>false</EnableBlockPlaced>
  <EnableGazeWarning>true</EnableGazeWarning>
  <EnableGazeActive>true</EnableGazeActive>
  <EnableGazeEnded>false</EnableGazeEnded>
  <EnableLowHealth>false</EnableLowHealth>
  <EnableDeath>true</EnableDeath>
</Vibration>
```

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `Enabled` | `true` | 全局开关。 |
| `GlobalIntensity` | `1` | 全局强度倍率（建议 0~2）。 |
| `AffectMainPlayer` | `true` | 是否只对本地主玩家生效。 |
| `EnableTakeDamage` | `true` | 受伤振动。 |
| `EnableAttackHit` | `true` | 攻击命中振动。 |
| `EnableBlockBroken` | `true` | 破坏方块振动。 |
| `EnableBlockPlaced` | `false` | 放置方块振动。 |
| `EnableGazeWarning` | `true` | 开始被注视振动（WhatLookMod）。 |
| `EnableGazeActive` | `true` | 注视激活振动（WhatLookMod）。 |
| `EnableGazeEnded` | `false` | 注视结束振动（WhatLookMod）。 |
| `EnableLowHealth` | `false` | 低生命值振动。 |
| `EnableDeath` | `true` | 死亡振动。 |

## 为其他模组提供振动事件

本模组对外暴露标准化接口。未引用本模组的模组可通过反射调用触发振动；引用了本模组的模组可直接调用。

### 直接引用（推荐）

```csharp
using Game;

// 触发标准事件
VibrationManager.Trigger(VibrationEventType.AttackHit);

// 自定义强度
VibrationManager.Trigger(VibrationEventType.TakeDamage, 1.5f);

// 注册自定义模式
VibrationManager.RegisterPattern(
    VibrationEventType.AttackHit,
    new VibrationPattern(
        new long[] { 0, 50, 30, 50 },
        new int[] { 0, 255, 0, 180 }
    )
);
```

### 反射调用（不引用本模组）

```csharp
using System;
using System.Reflection;

public static class VibrationBridge {
    private static Type s_managerType;
    private static MethodInfo s_triggerMethod;

    public static void Trigger(string eventTypeName, float intensity = 1f) {
        if (s_managerType == null) {
            foreach (Assembly assembly in AppDomain.CurrentDomain.GetAssemblies()) {
                s_managerType = assembly.GetType("Game.VibrationManager");
                if (s_managerType != null) break;
            }
            if (s_managerType == null) return;
            s_triggerMethod = s_managerType.GetMethod("Trigger", new[] { typeof(string), typeof(float) });
        }
        s_triggerMethod?.Invoke(null, new object[] { eventTypeName, intensity });
    }
}
```

调用示例：

```csharp
VibrationBridge.Trigger("GazeWarning");
VibrationBridge.Trigger("AttackHit", 0.8f);
```

支持的标准事件名称与 `VibrationEventType` 枚举名称一致，例如：

- `TakeDamage`
- `AttackHit`
- `BlockBroken`
- `BlockPlaced`
- `GazeWarning`
- `GazeActive`
- `GazeEnded`
- `LowHealth`
- `Death`

### 自定义 VibrationPattern

```csharp
var pattern = new VibrationPattern(
    timings: new long[] { 0, 100, 50, 100 },   // 立即振 100ms，停 50ms，再振 100ms
    amplitudes: new int[] { 0, 255, 0, 128 },  // 对应每段时间的振幅（0-255）
    repeat: -1,                                 // -1 不重复，0+ 为重复起始索引
    baseIntensity: 1f                           // 默认强度倍率
);
```

## 注意事项

- 振动仅在 Android 平台生效；Windows/Linux 等平台没有振动器，反射初始化会静默失败，不会导致游戏崩溃。
- 所有非关键日志已注释，仅保留 `Log.Error` 用于错误输出。
- 本模组为 `NonPersistentMod`，不写入存档，移除后不会产生缺失模组警告。
- 当前实现使用 `ModLoader` 钩子而非 Harmony 补丁，以减少与其他模组的冲突。

## 依赖

- Survivalcraft API 1.9.1 及以上
- HarmonyX（游戏内置）