VoteCommands

Vote Commands 0.2.0 — installation and configuration

This native update adds five templates copied from the 1.0.0 beta, without requiring PimpMyCUI. Compatible beta fixes are included; vote rules and scheduling remain those of the 0.1.3 LTS. This is a local, unpublished candidate.

Configure ballot choices

Under Vote, the table lists each choice and its active server commands and plugin calls. Click a name to edit its presentation, or Actions to set what runs if it wins. Add choice creates another option. A newly added action stays disabled until you enable it; check its parameters before using it.

Choose a template

In each oxide/config/VoteCommands/<name>.json, add or change:

"CuiTemplate": "operations-console",
"CuiTitle": "Blueprint policy",
"CuiQuestion": "Which blueprint policy should we use next wipe?"

Available values: operations-console (default), civic-ballot, relay-grid, arctic-council, broadcast-panel. Use legacy for the old interface configured through UIConfiguration; keep that existing section. Old files without the new fields use the default native template. Unknown template names reject that file with a console message.

Title and question are optional: missing, empty or null values use language messages. Reload with oxide.reload VoteCommands after editing; current votes stop without winner actions. Each controller can use its own template. Templates are embedded in the plugin; there are no extra CUI files or dependencies to install.

The UI shows three options per page with live counts and vote shares. Arrow buttons reach later choices. A player's selected choice remains marked after reopening. Each option uses its configured ImageUrl; an empty URL is valid. Set ImageAspectRatio to width/height (e.g. 1.5 for 900 × 600). The default is 1; images keep their aspect ratio.

Install or update

1. Back up your existing VoteCommands plugin, configurations and language file.
2. In the server console, run oxide.unload VoteCommands if it is already installed.
3. Copy the JSON files from this ZIP's oxide/config/VoteCommands/ into the server's matching folder. Do not overwrite any files you have customized: compare them or give new copies different names and unique chat commands.
4. Copy oxide/lang/en/VoteCommands.json if you do not already have a customized English language file.
5. Copy oxide/plugins/VoteCommands.cs last. The framework normally loads it automatically; otherwise run oxide.load VoteCommands.
6. Check the server console for Add VoteCommand Configuration : Example and any errors.

The paths above are relative to the server root for Oxide. On Carbon, use the corresponding carbon/plugins, carbon/config/VoteCommands and carbon/lang/en folders. The plugin uses the framework's configured config directory.

There is no single settings file at `oxide/config/VoteCommands.json`. Each vote has its own JSON file inside oxide/config/VoteCommands/.

If you install only the plugin, version 0.2.0 creates Example.json automatically when that directory contains no JSON files (including subfolders). It also registers default English messages. Existing JSON files are never overwritten. A malformed existing file produces a console error; it is not silently replaced. If all files are disabled, the plugin reports that no enabled votes were loaded.

First test (no winner commands are executed)

The supplied/generated Example.json is enabled, manual, and has all winner actions disabled.

1. Join as a server administrator.
2. In game chat, enter /vote_start.
3. Enter /vote and choose an option.
4. Wait 60 seconds for the result.
5. To let ordinary players vote, run this in the server console:

oxide.grant group default VoteCommands.Example.Vote

The permission contains the filename without .json, including its spelling. Rename the permission when you rename a configuration. The start command is administrator-only in this version; granting the registered VoteCommands.Example.Start permission alone does not make a non-admin eligible to start it. Ordinary players can view the ballot but need the Vote permission to participate.

Edit a vote

Edit a complete supplied JSON file; keep its UIConfiguration section. After saving, run oxide.reload VoteCommands. Reloading aborts current sessions without executing their winner actions and resets the schedule.

For a 60-second vote every 20 minutes, set VoteDurationSeconds to 60, TimeBetweenSessions to 1200, and AutomaticSessions to true. Also set AutomaticStart to true if this should begin automatically after loading.

Every enabled file must have a unique filename and two unique chat commands. Disabled or invalid files do not register their commands. Automatic schedules use elapsed time: the skip-night example does not detect sunset automatically.

Options and winner actions

Beta validation guards reject unsafe chat identifiers (32 characters maximum), callback identifiers (64 characters maximum), and enabled server commands with CR/LF/NUL or more than 256 characters. Identifiers allow letters, digits, dots, dashes and underscores. Non-empty image URLs must use HTTP or HTTPS without credentials, whitespace or control characters. Native HTTP support is retained. Rejected configuration files remain untouched; correct the reported field and reload.

Each entry under CommandsConfiguration.VoteCommands has a name, an image URL, and optional actions. Use direct image URLs; remotely hosted images must remain accessible.

{
  "Name": "Day",
  "ImageUrl": "https://i.postimg.cc/FkmPrP6v/4.png",
  "PluginCallbacks": null,
  "ServerCommands": [
    { "Enabled": true, "Command": "env.time 6" }
  ]
}

This is an option fragment, not a full configuration. A null action list is valid. Each action has its own Enabled flag. Test the exact command in the server console first, then enable it in the configuration.

For a plugin API with a no-argument hook, an option can instead (or also) use:

"PluginCallbacks": [
  { "Enabled": true, "PluginName": "YourPlugin", "PluginCallback": "YourHook" }
]

Replace both placeholders with an installed plugin and a real supported hook. The field is PluginCallbacks (plural); a callback does not accept arguments in this version. Enabled callbacks run before enabled server commands.

Included examples

Only Example.json is enabled by default. Set Enabled to true in a specialized example when you are ready to test it.

• Example.json — generic three-option, 60-second vote; /vote_start then /vote. All winner commands are disabled.
• Example_SkipNight.json — /vote_day_start then /vote_day, 60 seconds. Day executes env.time 6; Night leaves time unchanged. Once you enable this file, the Day action is live.
• Example_NextMapWipe.json — /vote_map_start then /vote_map, 300 seconds. Records the winning map only. It does not change the map, seed or wipe your server.
• Example_EventManager.json — /vote_event_start then /vote_event, 60 seconds. Requires a compatible EventManager installation and the optional EventManagerWrapper.cs. Copy that adapter into the server plugins folder only if you use EventManager. Configure your events in EventManager first, then replace DeathMatch, GunGame and CaptureTheFlag in the example commands with your actual event names. Vote Commands chooses an event; it does not define EventManager's event types or settings.

For another example, replace Example in the permission command with its filename, e.g. VoteCommands.Example_SkipNight.Vote.

Result behavior and limits

Each player can vote once per session. The option with the highest count wins. A tie between options with votes selects the first tied option in configuration order. If nobody votes, the session ends without a winner and runs no plugin callbacks or server commands. Automatic sessions continue at the configured interval; an empty server does not start an event by itself.

The core plugin requires neither EventManager nor PimpMyCUI. External winner commands/hooks require their owning plugins. The optional EventManager adapter and live UI must be tested against your installed server/plugin versions.

Customer test checklist

• Confirm version 0.2.0 loads and the example configuration is found (or generated on an otherwise empty installation).
• Open the generic example as admin, cast a vote, close/reopen the window, and confirm the result.
• Grant the matching Vote permission and test with a non-admin player.
• Verify labels, images and countdown in game.
• In a copy of the generic example with unique chat commands, use a short duration (e.g. 10 seconds), a longer interval (e.g. 20 seconds), and automatic sessions. Confirm at least three successive sessions, then disable it and reload.
• Try your desired winner command manually, then through one enabled vote.
• Let an automatic session end with zero votes and confirm that no winner command or plugin callback runs.
• Report console errors with the configuration filename, VoteCommands version and Oxide/Carbon version. Remove credentials and private server details.

Build contents

oxide/ contains the plugin, four complete example configurations and English/French messages. optional/ contains the EventManager adapter. CHANGELOG.md lists this patch's changes. Do not install the optional adapter if you do not use EventManager.