-
Notifications
You must be signed in to change notification settings - Fork 0
/
_DOC.txt
94 lines (91 loc) · 16.4 KB
/
_DOC.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
[GENERAL]
- This is an inputs framework, it allows developers to painlessly implement complex means of interfacing with the player and players to customize said interfaces to their liking.
- The system features translations: at the moment, English, Russian (thanks CrackbeardGunman) and Chinese (thanks ImmortalDamned) languages are supported. If there's a need for more, one can always offer their linguistic insight to fill in the blanks.
- The absolute majority of user-accessible features are explained in the form of the tooltips – make sure to read the text that pops up on hover. Additionally, seek "?" buttons, as they will provide some more explanations on mousing over.
- M-Nee is designed to allow seamless integration of both keyboard+mouse and gamepad input within a singular context. All the bindings can be assigned to both device categories interchangeably and the gamepad-exclusive part of the input features button-driven emulation modes.
- It is important to note that, while gamepad support is part of the inherent design of this system, the actual interface still has to be used with a mouse and keyboard. In fact, for the best experience, it is recommended to turn off vanilla gamepad support in its entirety – this can be done through Options -> Input -> Gamepad -> set to "Off", else conflicts and critical bugs may be encountered.
- To get started, it is recommended to visit Options -> Mod Settings -> M-Nee and follow the instructions provided there. One may also notice dead zone customization options and a full reset button.
- To provide certain flexibility, the input customization is performed on a per-profile case. There are 3 independent profiles in total and you may switch between them either through the listed hotkey or via the on-screen buttons in the M-Nee window. At the top right corner of the same window exists a global toggle button – a go-to option to immediately and safely cut off custom inputs.
- In addition to profiles, which are user-centric customization options, there are setup modes, a developer-focused input alteration subsystem. Setup modes allow one to have many button layout presets and to seamlessly switch between them without a loss of customizability.
- Another feature worth mentioning is the rebinding modes. There are two of them, simple and advanced. Where the former is the default straightforward way to assign a singular key to a basic action, the latter allows for any sort of complicated key groupings yet is more involved during rebinding as a result.
- Any action within the system supports secondary inputs, allowing a seamless transition from gamepad to keyboard and the other way around or any sort of alternative buttons to be assigned to the same input.
- Finally, any key can be unbound to be disabled permanently or at least until bound once again. One may find the toggle to do so at the bottom right of the rebinding menu.
[SETUP]
- First and foremost, please, consult this example of the reasonably advanced M-Nee setup: https://github.com/re-coilless/kappa
- Then, before the actual mnee.lua file structure will be elaborated upon, let us list some overarching utilities.
- In the mnee/lib.lua, at the top of the file, one will find a whole lot of globally relevant constants. Some of them are of no significance outside the internal context of the system itself, and some of them will be discussed later (see [MACRO] chapter), but two of such, mnee.SPECIAL_KEYS and mnee.INMODES, are of particular importance, as they can and should be modified by appending to the lib.lua itself.
- SPECIAL_KEYS is supposed to separate normal and "special" inputs, where a "special" input is handled in a rather particular way; if one is interested in mimicking the kind of functionality a key like "ctrl" or "alt" has, this is the very table one should write to.
- INMODES is of another yet no less fundamental purpose – it is the way to modify the global input itself; internally, this subsystem is used to create a parallel version of the key stream that only allows GUI-filtered LMB/RMB clicks and can be modified to implement any sort of interfacing, allowing phantom and custom keys to be injected.
- It must be noted that even with all the new fancy additions, the system is still fully backwards compatible: the Legacy section at the very bottom of the lib.lua is responsible for making sure it is so.
- Last but not least, seek mnee/lists.lua file – it has all of the internal key IDs / "encoding" layers written within itself and even contains a pair of handy controller inputs cheatsheets.
- Finally, it is time to consider how one would approach setting up a mnee-enabled mod. To begin, familiarize oneself with mnee/bindings.lua, which consists of two parts: mneedata and bindings.
- "mneedata" is the metadata table of the whole rebinding menu tab and has several fields all of which can be left empty. Actually, the entirety of this table can be skipped altogether with no detriment to the functionality of the rest of the system.
- name: the displayed name of the tab.
- desc: the tooltip text that appears while hovering over the tab.
- is_dirty: a global toggle that forces is_dirty mode for all bindings within this tab, unless their is_dirty field is not set to nil.
- is_advanced: a global toggle that does the same as is_dirty but for is_advanced option.
- is_locked: a global toggle that does the same as is_dirty but for is_locked option. Can be either a boolean or a function.
- is_hidden: hides the entire tab from the menu. Can be either a boolean or a function.
- func: a complete override of the tab contents allowing one to write a fully custom implementation; (data.a+1) is the index of the first elements at the current page, (data.b-1) is the index of the last element at the current page, data.ks is the entirety of the bindings table, "data.k_type" is either "keys" or "keys_alt" string value that corresponds to table index within every binding's structure; must return the uid argument followed by either nil or a "result" table where "result.set_bind" is the ID of the bind to be reassigned by the user, "result.will_axis" is the value that controls whether the bind is the axis or not, "result.btn_axis" is the toggle between emulated/real axis and "result.set_advanced" forces rebinding to be in the advanced mode.
- on_changed: callback that is run on binding getting altered (including it being set to default); "data" is mneedata table of the current mod.
- on_reset: callback that is run on full mod bindings reset, "on_changed" will be executed if it is nil; "data" is the same.
- on_jpad: callback that is run on every gamepad slot alteration, return true to set the updated slot to dummy-placeholder; "data" is the same, "jpad_id" is the gamepad slot id (is multiplied by -1 if is called on disconnect).
- on_setup: callback that is run on setup mode change; "data" is the setup_modes table, "setup_id" is the id of the applied setup.
- setup_default: a table for changing the appearance of the default setup mode; "setup_default.btn" is the displayed 3-letter long button name, "setup_default.name"/"setup_default.desc" are self-explanatory.
- setup_modes: a table of setup mode definitions; "setup_modes[].id" is an obligatory unique identificator of the mode, "setup_modes[].btn"/"setup_default.name"/"setup_default.desc" are exactly the same as described above, "setup_modes[].binds" is a string-indexed table of bindings to be replaced on application (see bindings.lua for an example).
- "bindings" is the main table of the system that declares the binds and all the relevant data that comes with them. This table must be defined for the system to function at all, yet out of all the fields only name, desc and keys are obligatory.
- order_id: is used to set custom sorting order for the normally alphabetically arranged bindings.
- is_dirty: setting this to true will alter the conflict-checking algorithm to compare bindings in a way like they had their is_dirty (see [INPUT] chapter) parameter enabled.
- is_advanced: will force the rebinding to be permanently in advanced mode (see [GENERAL] chapter).
- never_advanced: will prevent this bind to ever be changed in advanced mode.
- allow_special: despite the algorithm's better judgement, will force-allow special keys to be bound in the simple rebinding mode.
- is_locked: is used to prevent the setting from being changed by the user. Can be either a boolean or a function.
- is_hidden: is used to hide the existence of the binding from the user. Can be either a boolean or a function.
- name: the displayed name of the binding.
- desc: the tooltip text that appears while hovering over the binding.
- on_changed: callback that is run on binding getting altered; "data" is the table of the current bind.
- on_reset: callback that is run on the binding reset, "on_changed" will be executed if it is nil; "data" is the same.
- on_down: callback that is run on the binding activation; "data" is the same, "is_alt" enables one to pick between the keygroups, "is_jpad" reports whether the binding inputs from gamepad.
- jpad_type: the deadzone kind. There exist 4 (BUTTON, MOTION, AIM and EXTRA) and all can be changed in the normal settings. Only is relevant for the gamepad stick input.
- deadzone: is used to set an internal deadzone. Unlike "jpad_type", this parameter is inaccessible for the user – use it to create an inherent sensitivity difference between the controls.
- keys: a string-indexed table of the keys assigned to this bind by default.
- keys_alt: same as keys but for secondary input option.
- axes: two pre-existing axis binding IDs put in a table. This will allow one to create a legitimate stick with a circular deadzone. See mnee/lists.lua for a setup example.
[MACRO]
- Aside from the aforementioned SPECIAL_KEYS and INMODES, there exist 3 other useful global constants: mnee.TOGGLER, mnee.SERV_MODE and mnee.PRIO_MODE.
- TOGGLER is the global user-accessible mnee-base input toggle. It can be manually initiated via GameAddFlagRun( mnee.TOGGLER ) but keep in mind that the player always has the means of getting rid of this limitation. Bindings in VIP mode will ignore this toggle altogether.
- SERV_MODE is the same kind of toggle yet this time it is reserved for internal use. One may call it the same way as they did TOGGLER and it will be cleared on game reload to prevent softlocks. Bindings within whose context a global called mnee.ignore_service_mode was set to true will ignore this flag altogether.
- PRIO_MODE is the way to limit all input to a single mod alone. It can be enabled through mnee.set_priority_mode( mod_id ), replace "mod_id" with 0 to turn it off. It will be cleared on game reload to prevent softlocks. This toggle has no failsafe, so truly everything aside from the prioritized mod will be disabled no matter the case.
- Besides the constants, there exists several auxiliary functions, that cover niche use cases:
- mnee.get_triggers()/mnee.get_axes(): return raw analog input data in the following format – {1gpd_l2=value, 1gpd_r2=value}/{1gpd_axis_lh=value, 1gpd_axis_lv=value, 1gpd_axis_rh=value, 1gpd_axis_rv=value}.
- mnee.get_bindings( profile, binds_only ): returns all the binding data there is, basically the globalmost complete mnee table; "profile" controls from which profile to compile the data (default to current one on nil), "binds_only" removes miscellaneous fluff that is relevant only for visualization purposes. The structure is as follows – { mod_id = { bind_id = bind_table }}.
- mnee.get_binding_keys( mod_id, name, is_compact ): probably the most useful of them all, returns the keys of the bindings in a UI-friendly way; "mod_id" and "name" are for binding ID and "is_compact" set to true will make the return value take less space. The last arguement has an additional functionality of only returning primary or secondary binding – set it to 1 or 2 respectively.
- mnee.aim_assist( hooman, p_vec, angle, is_active, is_searching, data ): an all-in-one aim assist function that returns the aiming angle and whether it was affected by the target compared to the original, the strength can be altered in the settings; "hooman" and "pos" are character ID and a vector of their position, "angle" is the aiming direction, "is_active" toggles the function without a need for the if-case, "is_searching" controls whether the world will be scoured for projectiles to pull trajectory data for course corrections, "data.setting" dictates from which setting ID to pull strength value from, "data.tag_tbl" is the table of all the entity tags the autoaim will target, "data.pic" is the visualization of the target (set to "" to have none at all).
- mnee.is_jpad_real( id ): a basic utility for checking the connection state of a gamepad; "id" argument indicates the number of the controller and is equal to 1 by default.
- mnee.apply_jpads( jpad_tbl ): enables one to manually map gamepads to slots; "jpad_tbl" is a mapping table ("false" to unbound, 0-3 to assign).
- mnee.get_setup_id( mod_id, profile ): returns the id of currently active setup mode; "mod_id" is the id of the mod in questions, "profile" controls from which profile to compile the data (default to current one on nil).
- mnee.apply_setup( mod_id, setup_id ): forces chosen setup mode to be active; "mod_id" is the same as above, "setup_id" is the id of the mode to apply (defaults to standard mode on nil).
[INPUT]
- mnee.get_keyboard_input( no_shifting ) - a streamlined way to get full keyboard input
- Returns the first detected key, will only return one at a time.
- Supports shifting - will automatically detect the state change and return modified value (this will be disabled if "no_shifting" is true).
- Additionally, returns a set of special values for several func keys: return (3 normal, -3 shifted), escape (0 normal, nil shifted), backspace (2 normal, -2 shifted), tab (4 normal, -4 shifted).
- mnee.mnin( mode, id_data, data ) - a unified access point for the entirety of mnee input API
- mode: toggles the global behaviour of this function.
- id_data: serves to point to the binding in question.
- data: the actual input of the function.
- mnee.mnin( "key", {<key name>}, { dirty=dirty_mode, pressed=pressed_mode, vip=is_vip, mode=key_mode })
- Addresses the raw key by its internal name (see the list in bindings.lua), so unmodifiable and does not show up in the binding menu.
- dirty: will disable perma-false return on special key press (normally, it prevents conflicts between "ctrl+m" and "m" for example).
- pressed: will report "true" only once and then wait until the button is reset.
- vip: will ignore the TOGGLER flag (see [MACRO] chapter).
- mode: will choose between different INMODES profiles, set it to "guied" to filter out in-GUI LMB/RMB clicks.
- mnee.mnin( "bind", {<mod_id>, <binding name>}, { dirty=dirty_mode, pressed=pressed_mode, vip=is_vip, loose=loose_mode, mode=key_mode })
- Operates via flexible and rebindable single- or multi-keyed combinations, shows up in the binding menu and is a recommended way to set up the main input source. The second return value is a boolean of whether this action was unbound and the third is a check of whether any of the keys was assigned to the gamepad. Other than that, functions exactly like the one above.
- loose_mode: will allow a part of a larger combination to trigger a smaller one (for instance, "shift+ctrl+e" and "ctrl+e" would both be engaged).
- mnee.mnin( "axis", {<mod_id>, <binding name>}, { dirty=dirty_mode, pressed=pressed_mode, vip=is_vip, mode=key_mode })
- If binding is set to the proper analog axis, the output will be a number from -1.000 to 1.000 with 0 starting at the edge of the deadzone.
- If binding is set to discrete, the output will be forced to only three states(-1, 0 and 1), all according to the button presses. The third return value is a boolean of whether this action is button-emulated at the moment and the fourth is the repeat of what the one above had for third. Ignoring this, the mode behaves exactly as described before.
- mnee.mnin( "stick", {<mod_id>, <binding name>}, { dirty=dirty_mode, pressed=pressed_mode, vip=is_vip, mode=key_mode })
- The first return value is a two-element table of axis value, the third return value is a similarly-sized table of whether each of the axes is button-emulated and the fourth return value is the angle the stick is held at.
- Ignoring the above, the mode behaves exactly as described before.