Catalog versioned native hook points

crates/horizon-client/src/game/native_hooks.rs

@@ -650,6 +650,48 @@ mod tests {
         }
     }
 
+    #[test]
+    fn catalog_matches_hook_points() {
+        use std::collections::BTreeSet;
+
+        let catalog: serde_json::Value =
+            serde_json::from_str(include_str!("../../../../native-hooks.json")).unwrap();
+        let hooks = catalog["hooks"].as_array().unwrap();
+        let source = include_str!("native_hooks.rs");
+        let section = source
+            .split("/// The hook points. Each does nothing in Horizon.")
+            .nth(1)
+            .unwrap()
+            .split("/// Helpers for native mods")
+            .next()
+            .unwrap();
+        let declared: BTreeSet<_> = section
+            .lines()
+            .filter_map(|line| {
+                line.trim()
+                    .strip_prefix("pub(super) fn native_")?
+                    .split('(')
+                    .next()
+            })
+            .collect();
+        let mut names = BTreeSet::new();
+        let mut contracts = BTreeSet::new();
+        for hook in hooks {
+            let name = hook["name"].as_str().unwrap();
+            let version = hook["version"].as_u64().unwrap();
+            assert!(
+                version > 0 && contracts.insert((name, version)),
+                "invalid or duplicate hook: {name} v{version}"
+            );
+            names.insert(name);
+            assert_eq!(
+                hook["target"].as_str().unwrap(),
+                format!("horizon_client::game::native_hooks::Game<'_>::native_{name}")
+            );
+        }
+        assert_eq!(names, declared);
+    }
+
     /// Vanilla's F3 draws a column in each top corner (`extractLines`, left
     /// and right aligned), and its charts along the bottom.
     #[test]

docs/native-mods.md

@@ -141,3 +141,12 @@ Only the native builds an instance plays are kept (`native_mods::prune`); `nativ
 
 - Rebuild after the mods or the Nightly change (asking first, as it compiles for minutes).
 - A prebuilt horizon-mixins from its CI instead of building it on the player's computer.
+
+## Named hook catalog (draft)
+
+`native-hooks.json` maps stable hook names and contract versions to the current
+source targets. A contract includes the signature, call timing and behavior.
+Keep an existing contract or add a new version when it changes incompatibly.
+The catalog does not cover helper methods or arbitrary private game code.
+Named injection resolution needs a matching horizon-mixins change; existing raw
+targets and the `hooks` metadata continue to work as before.

native-hooks.json

@@ -0,0 +1,64 @@
+{
+  "hooks": [
+    {
+      "name": "frame",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_frame"
+    },
+    {
+      "name": "tick",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_tick"
+    },
+    {
+      "name": "hud",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_hud"
+    },
+    {
+      "name": "key",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_key"
+    },
+    {
+      "name": "wheel",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_wheel"
+    },
+    {
+      "name": "command",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_command"
+    },
+    {
+      "name": "zoom",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_zoom"
+    },
+    {
+      "name": "minimap",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_minimap"
+    },
+    {
+      "name": "mods",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_mods"
+    },
+    {
+      "name": "settings",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_settings"
+    },
+    {
+      "name": "settings_click",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_settings_click"
+    },
+    {
+      "name": "panel_event",
+      "version": 1,
+      "target": "horizon_client::game::native_hooks::Game<'_>::native_panel_event"
+    }
+  ]
+}