...
The new input system is an event driven script, allowing you to create a complete menu system. (The old system is still available)
Old vs New System
The old custom menu/get user input would allow you to get input from the user by displaying the menu, then waiting for the player to choose the option, which closes the menu and returns the result. Then the next input can be opened. The problem with this is that each input is not properly connected together, so it doesn't look quite right when opening multiple menus. This also ment that scripts had no control over the menu while its open (with the exception of manipulating the menu array externally)
...
The scriptname is the event script that controls the menu. You can also use them as part of the command console, where it replaces the preload option. Simply register the event script to the command you want (NOTE: you cant use a preload script if you set a menu script). Like the preload script, the final return value will be passed onto the command.
You can also use this in the new diplomacy commands.
Basic Usage
First, you need to create the event script. This should have 3 arguments, the first is the object the menu is to be run on, this would be the <RefObj> from the script command, or the ship/station object from the command console, or the Agent from the diplomacy commands. The second argument is the event state, this is a string for the current event. The final argument is the optional value array, and differs depending on the state that is called.
...
For some examples, you can check out the various diplomacy command menus.
Custom Menu, Return Value vs Next Input
When the input type is a custom menu, you can create them the same as the old custom menus, when setting a return value, then the menu will close, and send the return value to the event script.
You can also use the next input command
...
When selecting the next input, instead of running the event script with the id of the input, you will receive the event "returned" and the value will be an array, the first item in this array is the id of the input thats just been select, the second is the id of the menu it was run from, then the first third being the value that was selected (or null if it was cancelled) and finally the fourth is the current state of the menu array. Here you can return a new menu array, which will replace the existing menu (ie updating the menu display with new data) or you can return an input array to open another input straight away. Returning null here will just return back to the previous menu without making changes.
For examples of this, you can check out the Complex Planner or Custom Start menu scripts which utilise this.
Custom Menu, Callback return value
You can also create the callback return value for the menu items
...
For examples of this, you can check out the Ship Browser which uses the "select" event
Custom Menu Callback Options
When creating a custom menu input array, you can set the callback options. This is a set of flags (defined in constants) that allows to choose what other states you will receive.
...
For examples, you can check out the freight drone fetch and drop command menu for dynamic use of the trade bar. Or the Ship Browser menu script for dynamic value selections "switch"
Dynamic Custom Menus
You can also create dynamic custom menu (a different type of input array). The dynamic custom menus work in the same way as the normal custom menus, except they have additional events. The event "update" will be sent every time the menu is updated (redrawn) allowing you to update the menu dynamically.
...
If you want the menu to be dynamic so you can update it based on what's happening on the menu (selection changing, value selections, etc) Then it will be better to use the callback options instead. As these are called as soon as the item is changed, so there is no delay and saves having to constantly update the menu (only reacting to what's happening)
Context Menus
You can also display context menus when selecting an item from a custom menu. You create the context menu return value:
...
Similar to the info line command above, but its displayed for all items in the context menu, rather than per item
Scriptable Communication System
Short Explanation: Allows you to add and control comm options (of NPC ships) via an event script.
Currently used in following scripts:
...
There is currently 2 comm scripts implemented, one of them is "Surrender" option. This removes the old surrender comm option, and adds a new version. The 2nd, replaces the surrender and drop freight option
Generic Custom Input Event
| Event | Sent When | Return | Value Data | Extra Info |
|---|---|---|---|---|
| start |
...
| At the start of the input system |
...
| One of the |
...
| Input Arrays to open the next/first input | This is the value sent when starting the menu, ie from the script command | |
| finished |
...
Custom Menu Events
...
| Sent when the input has finished and closed | Allows for cleanup, ie removing global/local variables used | |||
| arguments | After the last input has returned | Array of arguments to pass to caller | If using from ship/agent command, the arguments are sent to the command script, otherwise the array is returned to the calling command | |
| cancelled | After any input is closed without selection | New Input array or null | The ID of the cancelled input | |
| closed | After the menu is forced closed externally | NOTE: this is rarely used | ||
| returned | After an "next" input menu has closed | an Input Array to open new or update previous menu | Array:
| This returns when a menu opened via "nextinput" is closed. This allows you to get the return value, and update the current menu |
| cmdcheck | before first input is open | CmdCheck constants | This is used to check if the command should be disabled/enabled. Ignored if not used with ship/agent command | |
| isdisabled | when parent menu is opened | BOOLEAN | ID of context menu item | Used for menus added to context menus/sidebar. Also used for diplomacy tasks |
| ishidden | When parent menu is opened | BOOLEAN | ID of context menu item | Used for menus added to context menus/siderbar. Can hide the command if needed |
Custom Menu Events
Some additional events will be used when using a custom menu
| Event | Start When | Return | Value Data | Extra Info |
|---|---|---|---|---|
| select | ||||
| switch | ||||
| selection | ||||
| escapepressed | ||||
| contextmenu | ||||
| contextmenu_update | ||||
| hotkey | ||||
| search | ||||
| group | ||||
| tradebar | ||||
| tradebar_changed | ||||
| update | ||||
| tabchanged | ||||
| heading_click | ||||
| tradebar_full | ||||
| tradebar_empty | ||||
| hyperlink |
Agent Command Events
When using a menu script with agent commands, some additional events are used to control the Diplomacy UI
| Event | Start When | Return | Value Data | Extra Info |
|---|---|---|---|---|
| allowmultiple | ||||
| influence | ||||
| isspy | ||||
| upkeep | ||||
| data |