接口速查

com.ifels.controlflex.api 的全部公开类型：入口、插件接口、四个 provider、状态注册表、叠层与相机接管、资源安装器。每节都给出签名与调用约束，代码片段可以直接抄。

本节： 概览 · 接入与生命周期 · 接口速查 · 官方实现 · 谁在用这套 API

类型总览

包名 com.ifels.controlflex.api，共 13 个公开类型。除 IPlayerStateRegistry.setState() 外，全部要求在客户端主线程调用。

ControlFlexApi（静态入口）

boolean isAvailable()               // installed and fully initialized
boolean isControllerConnected()     // a controller is connected

// Providers (null when unavailable)
IActionStateProvider getActionStateProvider()
IInputProvider getInputProvider()
IPlayerStateRegistry getPlayerStateRegistry()
IInteractiveContextRegistrar getInteractiveContextRegistrar()

String getApiVersion()              // e.g. "0.9.2"
void reloadGuides()                 // reload guide configs from disk

IActionStateProvider

boolean isGameActionActive(String actionId)   // game layer (no screen open)
boolean isGuiActionActive(String actionId)    // GUI layer
Set<String> getActiveGameActions()             // live view: never cache across ticks
Set<String> getActiveGuiActions()              // live view: never cache across ticks

动作 ID 三种写法：

• 内置动作：attack、use、jump、sneak、move_forward …
• 原版按键：key.jump、key.sneak
• 模组按键：epicfight:key.epicfight.attack（modId:keyName，键名不带 modid: 前缀）

IInputProvider · IControllerState · ICapabilities

// IInputProvider
boolean isConnected()
IControllerState getControllerState()          // null when disconnected
IControllerCapabilities getCapabilities()      // null when disconnected
String getGamepadName()                        // null when disconnected
int getGamepadIndex()                          // -1 when disconnected

// IControllerState — live view; sticks -1..1, triggers 0..1, +Y points down
float getLeftStickX()  / getLeftStickY()
float getRightStickX() / getRightStickY()
float getLeftTrigger() / getRightTrigger()
boolean isButtonAPressed() ... isDpadUpPressed() ...
boolean isButtonPressed(String buttonName)     // prefer ButtonName constants
float getAxisValue(String axisName)
boolean isShiftLayerActive()

// IControllerCapabilities
ControllerType getControllerType()   // XBOX / PLAYSTATION / NINTENDO_SWITCH / ...
boolean hasPaddles() / int getPaddleCount()
boolean hasTouchpad() / hasGyro() / hasRumble() / hasAnalogTriggers()
boolean isNintendoLayout()           // A/B swapped

ButtonName 提供按钮（A…Y、DPAD_UP、LEFT_BUMPER、LEFT_TRIGGER、LEFT_STICK_CLICK、BACK、START、GUIDE、PADDLE_1…PADDLE_4、TOUCHPAD）、摇杆方向（LEFT_STICK_UP …）与轴（AXIS_LEFT_X、AXIS_RIGHT_TRIGGER …）三组常量。

IPlayerStateRegistry

void setState(String stateKey, boolean active)  // thread-safe, callable from any thread
boolean getState(String stateKey)               // client thread
void clearState(String stateKey)                // drop the registration

stateKey 形如 modId:stateName（如 epicfight:battle_mode），就是 compat JSON 里 itemSuppressKeys[].playerState 读的那个字符串。

ICameraLookConsumer（0.8.8+）

boolean consumeLook(float yaw, float pitch)
// true  = this frame's look is consumed: Control Flex must not write player rotation
// false = not consumed: Control Flex keeps its normal path

• 用途：模组接管了渲染相机（Epic Fight 的 TPS 战斗视角、锁定目标等），此时玩家的 yRot/xRot 不再是画面来源，必须把视角增量转交给那个模组。
• 每帧最多调用一次，参数是转向之前标定过的增量，与原版鼠标管线交给接管方的是同一个尺度。
• 在插件里覆写 cameraLookConsumer() 返回实现；返回 null（默认）表示不接管。

IInteractiveContextRegistrar

void notifyOverlayForeground(String className)   // overlay entered the foreground
void notifyOverlayBackground(String className)   // overlay went back (pairs with foreground)
void clearAll()                                  // fallback: world unload / mod shutdown

className 是全限定类名 —— Control Flex 拿它去 compat JSON 的 overlay 表里查摇杆与光标行为。调用前先判空：getInteractiveContextRegistrar() 可能是 null。

ICompatAssetInstaller

boolean install(String resourcePath, String fileName)
// resourcePath: classpath path inside your jar, e.g. "/assets/mymod/compat/targetmod_keys.json"
// fileName:     target file name inside compat/mods/ or guides/mods/
// returns:      true when installed

继续读