Skip to content

Commit 3831858

Browse files
xiaoxiao921xiaoxiao921
committed
- fixes for lua doc, get rid of — character messing up file encoding
- doc gen
1 parent bdfec08 commit 3831858

7 files changed

Lines changed: 382 additions & 44 deletions

File tree

‎docs/lua/tables/_ENV - Plugin Specific Global Table.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ for n in pairs(rom.mods[_ENV._PLUGIN.guid]) do
2121
end
2222
```
2323

24-
## Fields (8)
24+
## Fields (9)
2525

2626
### `_PLUGIN.guid`
2727

@@ -69,3 +69,10 @@ Path to the mod folder inside `plugins`
6969

7070
- Type: `lua_module*`
7171

72+
### `_PLUGIN.sjson_data_path`
73+
74+
The absolute path to the plugin's SJSON data directory (plugins_data/<mod-guid>/Hell2Modding-SJSON/).
75+
Mod authors can use this to discover or create .sjson files at runtime.
76+
77+
- Type: `string`
78+

‎docs/lua/tables/definitions/_ENV - Plugin Specific Global Table.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,5 @@
2929
---@field _PLUGIN.plugins_data_mod_folder_path string # Path to the mod folder inside `plugins_data`
3030
---@field _PLUGIN.plugins_mod_folder_path string # Path to the mod folder inside `plugins`
3131
---@field _PLUGIN.this lua_module*
32+
---@field _PLUGIN.sjson_data_path string # The absolute path to the plugin's SJSON data directory (plugins_data/<mod-guid>/Hell2Modding-SJSON/).Mod authors can use this to discover or create .sjson files at runtime.
3233

‎docs/lua/tables/definitions/rom.data.lua‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---@meta data
22

33
---@class (exact) rom.data
4+
---@field SJSON_DATA_DIR_NAME string # Value: "Hell2Modding-SJSON"The canonical directory name for the SJSON data overlay.Mods must place .sjson files in plugins_data/<mod-guid>/<SJSON_DATA_DIR_NAME>/Animations/, Text/{lang}/, etc.Hell2Modding scans this directory at startup and injects discovered .sjson files into the engine's loading pipeline.
45

56
---@param hash_guid integer Hash value.
67
---@return string # Returns the string corresponding to the provided hash value.
@@ -29,10 +30,114 @@ function data.load_package_overrides_get(hash_guid) end
2930
---@param hash_guid_table_override table<number> List of HashGuid values that should be used instead.
3031
function data.load_package_overrides_set(hash_guid, hash_guid_table_override) end
3132

33+
-- Registers a custom GPK file for file-redirection at runtime, allowing
34+
--hot-loading of GPK assets that were not present during initial scan.
35+
--
36+
--**Example Usage:**
37+
--```lua
38+
--rom.rom.data.add_granny_file("Melinoe.gpk", "C:/path/to/plugins_data/CG3HBuilder/Melinoe.gpk")
39+
--```
40+
---@param filename string The GPK filename (e.g. "Melinoe.gpk").
41+
---@param full_path string The full filesystem path to the GPK file.
42+
function data.add_granny_file(filename, full_path) end
43+
44+
-- Registers a custom PKG/PKG_MANIFEST file for file-redirection at runtime.
45+
--
46+
--**Example Usage:**
47+
--```lua
48+
--rom.rom.data.add_package_file("MyMod.pkg", "C:/path/to/plugins_data/MyMod/MyMod.pkg")
49+
--```
50+
---@param filename string The PKG or PKG_MANIFEST filename.
51+
---@param full_path string The full filesystem path to the file.
52+
function data.add_package_file(filename, full_path) end
53+
3254
---@param function function Function called when game data file is read. The function must match signature: (string (file_path_being_read), string (file_content_buffer)) -> returns nothing (nil) or the new file buffer (string)
3355
---@param file_path_being_read string optional. Use only if you want your lua function to be called for a given file_path.
3456
function data.on_sjson_read_as_string(function, file_path_being_read) end
3557

3658
function data.reload_game_data() end
3759

60+
-- Registers a .sjson file so the engine discovers and loads it as if it were in the game's `Content/Game/` directory.
61+
--The engine-relative path is inferred automatically: files inside `plugins_data/<mod>/<SJSON_DATA_DIR_NAME>/` map to `Content/Game/`.
62+
--For example, `plugins_data/<mod-guid>/<SJSON_DATA_DIR_NAME>/Animations/Foo.sjson` is loaded as `Content/Game/Animations/Foo.sjson`.
63+
--At startup, Hell2Modding automatically scans every mod's <SJSON_DATA_DIR_NAME> directory and registers any .sjson files found.
64+
--Use this function to dynamically register files created during the current session (e.g. a first-time install placing a file into plugins_data).
65+
---@param absolute_path string The absolute filesystem path to a .sjson file inside a <SJSON_DATA_DIR_NAME> directory.
66+
---@return boolean # true if registered successfully, false if the file is a duplicate, not a .sjson, or the path does not contain <SJSON_DATA_DIR_NAME>.
67+
function data.register_sjson_file(absolute_path) end
68+
69+
-- Scans the directory recursively and registers all .sjson files found. Each file's engine path is derived from its position in the directory tree.
70+
--This is the same scan that Hell2Modding performs automatically at startup for `plugins_data/*/<SJSON_DATA_DIR_NAME>/`.
71+
---@param absolute_base_path string Absolute path to a directory whose structure mirrors `Content/Game/` (e.g. containing `Animations/`, `Text/en/`, etc.)
72+
function data.register_content_directory(absolute_base_path) end
73+
74+
-- Registers a file redirect so the engine loads it from an external location instead of Content/.
75+
--Unlike register_content_file (SJSON-only), this works for any file type that the engine loads via fsAppendPathComponent (maps, etc.).
76+
--No directory convention is enforced - the caller provides both paths.
77+
---@param content_relative_path string The path relative to Content/, e.g. "Maps/D_Hub.map_text" or "Maps/bin/D_Hub.thing_bin"
78+
---@param absolute_path string The absolute filesystem path to the actual file
79+
---@return boolean # true if registered, false if duplicate
80+
function data.register_file_redirect(content_relative_path, absolute_path) end
81+
82+
-- Registers a file for engine injection and redirect. Routes to the appropriate internal registry.
83+
--Supported extensions: .map_text, .thing_bin, .bik, .bik_atlas, .fsb, .txt.
84+
--SJSON files should use `register_sjson_file` instead.
85+
---@param filename string The filename (e.g. "D_Boss01.map_text", "HadesBattleIdle.bik", "Zagreus.fsb")
86+
---@param absolute_path string The absolute filesystem path to the file
87+
---@return boolean # true if registered, false if already registered or unsupported extension
88+
function data.register_plugin_file(filename, absolute_path) end
89+
90+
-- Toggles visibility of a model entry. Takes effect immediately.
91+
--
92+
--**Example Usage:**
93+
--```lua
94+
--rom.rom.data.draw_set_visible("HecateBattle_Mesh", false)
95+
--```
96+
---@param entry_name string Model entry name (e.g. "HecateBattle_Mesh").
97+
---@param visible boolean true to show, false to hide.
98+
function data.draw_set_visible(entry_name, visible) end
99+
100+
-- Logs vertex-pool and index-pool capacity and cursor usage.
101+
--Diagnostic only: useful when tuning the pool size config
102+
--against a mod load-out.
103+
---@return number # number of per-shader vertex buffers dumped.
104+
function data.draw_dump_pool_stats() end
105+
106+
-- Resolves the entry's mesh textures up-front. Useful for
107+
--entries that aren't in the active scene (loaded-but-not-drawn
108+
--variants) so their first drawn frame doesn't render white.
109+
---@param entry_name string
110+
---@return integer # number of textures populated.
111+
function data.draw_populate_entry_textures(entry_name) end
112+
113+
-- Finer-grained than draw_set_visible: toggles a single named
114+
--mesh inside an entry instead of the whole entry.
115+
---@param entry_name string Model entry (e.g. "HecateHub_Mesh").
116+
---@param mesh_name string Mesh name inside that entry (e.g. "TorusHubMesh").
117+
---@param visible boolean true to show, false to hide.
118+
---@return boolean # true on success.
119+
function data.draw_set_mesh_visible(entry_name, mesh_name, visible) end
120+
121+
-- Redirects draw calls for `stock_entry` to `variant_entry`.
122+
--Use draw_populate_entry_textures on the variant first (ideally
123+
--from a safe window like the first ImGui frame): this call is a
124+
--cheap map write and is not safe to call GetTexture from.
125+
--
126+
--**Example Usage:**
127+
--```lua
128+
--rom.data.draw_populate_entry_textures("HecateHub_Variant_Mesh")
129+
--rom.rom.data.draw_swap_to_variant("HecateHub_Mesh", "HecateHub_Variant_Mesh")
130+
---- later:
131+
--rom.data.draw_restore_stock("HecateHub_Mesh")
132+
--```
133+
---@param stock_entry string Stock entry name (e.g. "HecateHub_Mesh").
134+
---@param variant_entry string Variant entry name loaded in mModelData.
135+
---@return boolean # true on success.
136+
function data.draw_swap_to_variant(stock_entry, variant_entry) end
137+
138+
-- Clears any active hash remap for the given stock entry.
139+
---@param stock_entry string Stock entry name to revert to.
140+
---@return boolean # true on success.
141+
function data.draw_restore_stock(stock_entry) end
142+
38143

‎docs/lua/tables/rom.data.md‎

Lines changed: 226 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
# Table: rom.data
22

3-
## Functions (6)
3+
## Fields (1)
4+
5+
### `SJSON_DATA_DIR_NAME`
6+
7+
Value: "Hell2Modding-SJSON"
8+
The canonical directory name for the SJSON data overlay.
9+
Mods must place .sjson files in plugins_data/<mod-guid>/<SJSON_DATA_DIR_NAME>/Animations/, Text/{lang}/, etc.
10+
Hell2Modding scans this directory at startup and injects discovered .sjson files into the engine's loading pipeline.
11+
12+
- Type: `string`
13+
14+
## Functions (18)
415

516
### `get_string_from_hash_guid(hash_guid)`
617

@@ -65,6 +76,43 @@ rom.rom.data.load_package_overrides_set(gui_hash, {gui_hash, some_custom_hash})
6576
rom.data.load_package_overrides_set(hash_guid, hash_guid_table_override)
6677
```
6778

79+
### `add_granny_file(filename, full_path)`
80+
81+
Registers a custom GPK file for file-redirection at runtime, allowing
82+
hot-loading of GPK assets that were not present during initial scan.
83+
84+
**Example Usage:**
85+
```lua
86+
rom.rom.data.add_granny_file("Melinoe.gpk", "C:/path/to/plugins_data/CG3HBuilder/Melinoe.gpk")
87+
```
88+
89+
- **Parameters:**
90+
- `filename` (string): The GPK filename (e.g. "Melinoe.gpk").
91+
- `full_path` (string): The full filesystem path to the GPK file.
92+
93+
**Example Usage:**
94+
```lua
95+
rom.data.add_granny_file(filename, full_path)
96+
```
97+
98+
### `add_package_file(filename, full_path)`
99+
100+
Registers a custom PKG/PKG_MANIFEST file for file-redirection at runtime.
101+
102+
**Example Usage:**
103+
```lua
104+
rom.rom.data.add_package_file("MyMod.pkg", "C:/path/to/plugins_data/MyMod/MyMod.pkg")
105+
```
106+
107+
- **Parameters:**
108+
- `filename` (string): The PKG or PKG_MANIFEST filename.
109+
- `full_path` (string): The full filesystem path to the file.
110+
111+
**Example Usage:**
112+
```lua
113+
rom.data.add_package_file(filename, full_path)
114+
```
115+
68116
### `on_sjson_read_as_string(function, file_path_being_read)`
69117

70118
- **Parameters:**
@@ -83,4 +131,181 @@ rom.data.on_sjson_read_as_string(function, file_path_being_read)
83131
rom.data.reload_game_data()
84132
```
85133

134+
### `register_sjson_file(absolute_path)`
135+
136+
Registers a .sjson file so the engine discovers and loads it as if it were in the game's `Content/Game/` directory.
137+
The engine-relative path is inferred automatically: files inside `plugins_data/<mod>/<SJSON_DATA_DIR_NAME>/` map to `Content/Game/`.
138+
For example, `plugins_data/<mod-guid>/<SJSON_DATA_DIR_NAME>/Animations/Foo.sjson` is loaded as `Content/Game/Animations/Foo.sjson`.
139+
At startup, Hell2Modding automatically scans every mod's <SJSON_DATA_DIR_NAME> directory and registers any .sjson files found.
140+
Use this function to dynamically register files created during the current session (e.g. a first-time install placing a file into plugins_data).
141+
142+
- **Parameters:**
143+
- `absolute_path` (string): The absolute filesystem path to a .sjson file inside a <SJSON_DATA_DIR_NAME> directory.
144+
145+
- **Returns:**
146+
- `boolean`: true if registered successfully, false if the file is a duplicate, not a .sjson, or the path does not contain <SJSON_DATA_DIR_NAME>.
147+
148+
**Example Usage:**
149+
```lua
150+
boolean = rom.data.register_sjson_file(absolute_path)
151+
```
152+
153+
### `register_content_directory(absolute_base_path)`
154+
155+
Scans the directory recursively and registers all .sjson files found. Each file's engine path is derived from its position in the directory tree.
156+
This is the same scan that Hell2Modding performs automatically at startup for `plugins_data/*/<SJSON_DATA_DIR_NAME>/`.
157+
158+
- **Parameters:**
159+
- `absolute_base_path` (string): Absolute path to a directory whose structure mirrors `Content/Game/` (e.g. containing `Animations/`, `Text/en/`, etc.)
160+
161+
**Example Usage:**
162+
```lua
163+
rom.data.register_content_directory(absolute_base_path)
164+
```
165+
166+
### `register_file_redirect(content_relative_path, absolute_path)`
167+
168+
Registers a file redirect so the engine loads it from an external location instead of Content/.
169+
Unlike register_content_file (SJSON-only), this works for any file type that the engine loads via fsAppendPathComponent (maps, etc.).
170+
No directory convention is enforced - the caller provides both paths.
171+
172+
- **Parameters:**
173+
- `content_relative_path` (string): The path relative to Content/, e.g. "Maps/D_Hub.map_text" or "Maps/bin/D_Hub.thing_bin"
174+
- `absolute_path` (string): The absolute filesystem path to the actual file
175+
176+
- **Returns:**
177+
- `boolean`: true if registered, false if duplicate
178+
179+
**Example Usage:**
180+
```lua
181+
boolean = rom.data.register_file_redirect(content_relative_path, absolute_path)
182+
```
183+
184+
### `register_plugin_file(filename, absolute_path)`
185+
186+
Registers a file for engine injection and redirect. Routes to the appropriate internal registry.
187+
Supported extensions: .map_text, .thing_bin, .bik, .bik_atlas, .fsb, .txt.
188+
SJSON files should use `register_sjson_file` instead.
189+
190+
- **Parameters:**
191+
- `filename` (string): The filename (e.g. "D_Boss01.map_text", "HadesBattleIdle.bik", "Zagreus.fsb")
192+
- `absolute_path` (string): The absolute filesystem path to the file
193+
194+
- **Returns:**
195+
- `boolean`: true if registered, false if already registered or unsupported extension
196+
197+
**Example Usage:**
198+
```lua
199+
boolean = rom.data.register_plugin_file(filename, absolute_path)
200+
```
201+
202+
### `draw_set_visible(entry_name, visible)`
203+
204+
Toggles visibility of a model entry. Takes effect immediately.
205+
206+
**Example Usage:**
207+
```lua
208+
rom.rom.data.draw_set_visible("HecateBattle_Mesh", false)
209+
```
210+
211+
- **Parameters:**
212+
- `entry_name` (string): Model entry name (e.g. "HecateBattle_Mesh").
213+
- `visible` (boolean): true to show, false to hide.
214+
215+
**Example Usage:**
216+
```lua
217+
rom.data.draw_set_visible(entry_name, visible)
218+
```
219+
220+
### `draw_dump_pool_stats()`
221+
222+
Logs vertex-pool and index-pool capacity and cursor usage.
223+
Diagnostic only: useful when tuning the pool size config
224+
against a mod load-out.
225+
226+
- **Returns:**
227+
- `number`: number of per-shader vertex buffers dumped.
228+
229+
**Example Usage:**
230+
```lua
231+
number = rom.data.draw_dump_pool_stats()
232+
```
233+
234+
### `draw_populate_entry_textures(entry_name)`
235+
236+
Resolves the entry's mesh textures up-front. Useful for
237+
entries that aren't in the active scene (loaded-but-not-drawn
238+
variants) so their first drawn frame doesn't render white.
239+
240+
- **Parameters:**
241+
- `entry_name` (string)
242+
243+
- **Returns:**
244+
- `integer`: number of textures populated.
245+
246+
**Example Usage:**
247+
```lua
248+
integer = rom.data.draw_populate_entry_textures(entry_name)
249+
```
250+
251+
### `draw_set_mesh_visible(entry_name, mesh_name, visible)`
252+
253+
Finer-grained than draw_set_visible: toggles a single named
254+
mesh inside an entry instead of the whole entry.
255+
256+
- **Parameters:**
257+
- `entry_name` (string): Model entry (e.g. "HecateHub_Mesh").
258+
- `mesh_name` (string): Mesh name inside that entry (e.g. "TorusHubMesh").
259+
- `visible` (boolean): true to show, false to hide.
260+
261+
- **Returns:**
262+
- `boolean`: true on success.
263+
264+
**Example Usage:**
265+
```lua
266+
boolean = rom.data.draw_set_mesh_visible(entry_name, mesh_name, visible)
267+
```
268+
269+
### `draw_swap_to_variant(stock_entry, variant_entry)`
270+
271+
Redirects draw calls for `stock_entry` to `variant_entry`.
272+
Use draw_populate_entry_textures on the variant first (ideally
273+
from a safe window like the first ImGui frame): this call is a
274+
cheap map write and is not safe to call GetTexture from.
275+
276+
**Example Usage:**
277+
```lua
278+
rom.data.draw_populate_entry_textures("HecateHub_Variant_Mesh")
279+
rom.rom.data.draw_swap_to_variant("HecateHub_Mesh", "HecateHub_Variant_Mesh")
280+
-- later:
281+
rom.data.draw_restore_stock("HecateHub_Mesh")
282+
```
283+
284+
- **Parameters:**
285+
- `stock_entry` (string): Stock entry name (e.g. "HecateHub_Mesh").
286+
- `variant_entry` (string): Variant entry name loaded in mModelData.
287+
288+
- **Returns:**
289+
- `boolean`: true on success.
290+
291+
**Example Usage:**
292+
```lua
293+
boolean = rom.data.draw_swap_to_variant(stock_entry, variant_entry)
294+
```
295+
296+
### `draw_restore_stock(stock_entry)`
297+
298+
Clears any active hash remap for the given stock entry.
299+
300+
- **Parameters:**
301+
- `stock_entry` (string): Stock entry name to revert to.
302+
303+
- **Returns:**
304+
- `boolean`: true on success.
305+
306+
**Example Usage:**
307+
```lua
308+
boolean = rom.data.draw_restore_stock(stock_entry)
309+
```
310+
86311

0 commit comments

Comments
 (0)