|
| 1 | +# Logistics Plugin |
| 2 | + |
| 3 | +A comprehensive logistics mission system for DCSServerBot with full DCS in-game integration. Create, manage, and track cargo delivery missions with F10 map markers, in-game chat commands, and automatic delivery detection. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Task Management**: Create and manage logistics delivery tasks via Discord |
| 8 | +- **In-Game Integration**: View and accept tasks via F10 menu or chat commands |
| 9 | +- **F10 Map Markers**: Visual route markers showing pickup, delivery, waypoints with cargo/pilot/deadline info |
| 10 | +- **Auto-Completion**: Automatic task completion when pilot lands at destination |
| 11 | +- **Logbook Integration**: Completed tasks are credited to pilot's logbook record |
| 12 | +- **Warehouse Queries**: Query airbase/carrier inventory via Discord commands |
| 13 | +- **Coalition-Specific**: All markers and tasks are coalition-restricted |
| 14 | + |
| 15 | +## Requirements |
| 16 | + |
| 17 | +- DCSServerBot v3.6+ |
| 18 | +- **missionstats plugin** must be enabled (provides `onMissionEvent` for landing detection) |
| 19 | +- **logbook plugin** (optional) - enables pilot credit for completed deliveries |
| 20 | + |
| 21 | +## Installation |
| 22 | + |
| 23 | +1. Add `logistics` to `opt_plugins` in your `config/main.yaml`: |
| 24 | + ```yaml |
| 25 | + opt_plugins: |
| 26 | + - logistics |
| 27 | + ``` |
| 28 | +
|
| 29 | +2. Restart DCSServerBot - the database tables will be created automatically |
| 30 | +
|
| 31 | +3. (Optional) Configure the plugin in `config/plugins/logistics.yaml` |
| 32 | + |
| 33 | +## Configuration |
| 34 | + |
| 35 | +```yaml |
| 36 | +# config/plugins/logistics.yaml |
| 37 | +DEFAULT: |
| 38 | + enabled: true |
| 39 | + delivery: |
| 40 | + proximity_threshold: 3000 # Detection radius in meters |
| 41 | + require_landing: true # Require landing event for auto-complete |
| 42 | + markers: |
| 43 | + enabled: true |
| 44 | + show_deadline: true |
| 45 | + tasks: |
| 46 | + auto_approve: false # Auto-approve player requests |
| 47 | + timeout_hours: 24 # Task expiration |
| 48 | + max_per_player: 1 # Max concurrent tasks per player |
| 49 | +``` |
| 50 | + |
| 51 | +## Discord Commands |
| 52 | + |
| 53 | +### Task Management (`/logistics`) |
| 54 | + |
| 55 | +| Command | Description | Role | |
| 56 | +|---------|-------------|------| |
| 57 | +| `/logistics create <server> <cargo> <source> <destination> [coalition] [priority] [deadline]` | Create a logistics task | DCS Admin | |
| 58 | +| `/logistics list [server] [status] [coalition]` | List tasks with filters | DCS | |
| 59 | +| `/logistics view <task>` | View task details | DCS | |
| 60 | +| `/logistics approve <task>` | Approve pending task | DCS Admin | |
| 61 | +| `/logistics deny <task> [reason]` | Deny pending task | DCS Admin | |
| 62 | +| `/logistics cancel <task>` | Cancel any task | DCS Admin | |
| 63 | + |
| 64 | +### Warehouse Commands (`/warehouse`) |
| 65 | + |
| 66 | +| Command | Description | Role | |
| 67 | +|---------|-------------|------| |
| 68 | +| `/warehouse status <server> <airbase>` | Query inventory at location | DCS | |
| 69 | +| `/warehouse compare <server> <source> <destination>` | Compare two locations | DCS | |
| 70 | + |
| 71 | +## In-Game Chat Commands |
| 72 | + |
| 73 | +| Command | Description | |
| 74 | +|---------|-------------| |
| 75 | +| `-tasks` | List available logistics tasks for your coalition | |
| 76 | +| `-accept <id>` | Accept/claim a logistics task | |
| 77 | +| `-mytask` | Show your current assigned task | |
| 78 | +| `-taskinfo <id>` | View details of any visible task | |
| 79 | +| `-deliver` | Mark current task as delivered (manual) | |
| 80 | +| `-abandon` | Release task back to available pool | |
| 81 | +| `-request <dest> <cargo>` | Player-initiated logistics request | |
| 82 | + |
| 83 | +## F10 Menu Structure |
| 84 | + |
| 85 | +``` |
| 86 | +Logistics/ |
| 87 | +├── View Available Tasks (Show popup with available tasks) |
| 88 | +├── My Current Task (Show your assigned task details) |
| 89 | +├── Accept Task/ (Submenu with available tasks) |
| 90 | +│ ├── #1: Mk-82 -> Akrotiri |
| 91 | +│ ├── #2!: Fuel -> Illustrious (! = urgent) |
| 92 | +│ └── ... |
| 93 | +├── Mark Delivered (Manual completion - when assigned) |
| 94 | +└── Abandon Task (Release task - when assigned) |
| 95 | +``` |
| 96 | +
|
| 97 | +## F10 Map Markers |
| 98 | +
|
| 99 | +When a task is approved, coalition-specific markers appear on the F10 map: |
| 100 | +
|
| 101 | +- **Source Marker** (Green): `[PICKUP] Airbase Name` |
| 102 | +- **Destination Marker** (Yellow): |
| 103 | + ``` |
| 104 | + [DELIVERY] Airbase Name |
| 105 | + Cargo: 10x Mk-82 |
| 106 | + Pilot: Maverick (or UNASSIGNED) |
| 107 | + Deadline: 14:30Z |
| 108 | + ``` |
| 109 | +- **Waypoint Markers** (Yellow): `[VIA 1] Waypoint Name` |
| 110 | +- **Route Lines** (Yellow): Connecting source -> waypoints -> destination |
| 111 | +
|
| 112 | +## Delivery Detection |
| 113 | +
|
| 114 | +Tasks are automatically completed when: |
| 115 | +
|
| 116 | +1. **Primary**: Player lands at the destination airbase/FARP/carrier (detected via `S_EVENT_LAND`) |
| 117 | +2. **Secondary**: Player's aircraft is within proximity threshold of destination position |
| 118 | +3. **Fallback**: Manual `-deliver` command or F10 menu "Mark Delivered" |
| 119 | +
|
| 120 | +## Task Workflow |
| 121 | +
|
| 122 | +``` |
| 123 | +┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ |
| 124 | +│ pending │────>│ approved │────>│ assigned │────>│ completed │ |
| 125 | +└─────────┘ └──────────┘ └──────────┘ └───────────┘ |
| 126 | + │ │ │ |
| 127 | + │ │ │ |
| 128 | + v v v |
| 129 | + ┌────────┐ ┌─────────┐ ┌───────────┐ |
| 130 | + │ denied │ │cancelled│ │ failed │ |
| 131 | + └────────┘ └─────────┘ └───────────┘ |
| 132 | +``` |
| 133 | +
|
| 134 | +- **pending**: Created by Discord command or player request, awaiting approval |
| 135 | +- **approved**: Approved by admin, visible on map, available for acceptance |
| 136 | +- **assigned**: Claimed by a pilot, shown with pilot name on markers |
| 137 | +- **in_progress**: (Optional) Pilot has picked up cargo |
| 138 | +- **completed**: Delivered successfully, credited to pilot's logbook |
| 139 | +- **failed**: Task failed (timeout, other issues) |
| 140 | +- **cancelled**: Cancelled by admin |
| 141 | +- **denied**: Request denied by admin |
| 142 | +
|
| 143 | +## Logbook Integration |
| 144 | +
|
| 145 | +When a logistics task is completed, the pilot receives credit in the `logbook_logistics_completions` table: |
| 146 | +
|
| 147 | +| Field | Description | |
| 148 | +|-------|-------------| |
| 149 | +| player_ucid | Pilot's unique ID | |
| 150 | +| task_id | Completed task reference | |
| 151 | +| cargo_type | What was delivered | |
| 152 | +| source_name | Pickup location | |
| 153 | +| destination_name | Delivery location | |
| 154 | +| completed_at | Completion timestamp | |
| 155 | +
|
| 156 | +This data can be used for: |
| 157 | +- Displaying logistics stats in `/logbook stats` |
| 158 | +- Auto-granting qualifications (e.g., "Logistics Specialist" after 10 deliveries) |
| 159 | +- Squadron statistics |
| 160 | +
|
| 161 | +## Database Schema |
| 162 | +
|
| 163 | +The plugin creates the following tables: |
| 164 | +
|
| 165 | +- `logistics_tasks` - Task definitions with status, positions, assignments |
| 166 | +- `logistics_tasks_history` - Audit trail of task events |
| 167 | +- `logistics_markers` - F10 marker ID tracking for cleanup |
| 168 | +- `logbook_logistics_completions` - Pilot delivery records |
| 169 | +
|
| 170 | +## Migration from /stores |
| 171 | +
|
| 172 | +If you were using the `/stores` commands from the logbook plugin, note that logistics replaces that functionality entirely with a more comprehensive system. The old `logbook_stores_requests` table is preserved for reference but no longer actively used. |
| 173 | +
|
| 174 | +## Troubleshooting |
| 175 | +
|
| 176 | +### Markers not appearing |
| 177 | +- Ensure the task has `source_position` and `destination_position` set |
| 178 | +- Verify player is on the correct coalition |
| 179 | +- Check DCS.log for Lua errors |
| 180 | +
|
| 181 | +### Auto-completion not working |
| 182 | +- Ensure missionstats plugin is enabled (provides landing events) |
| 183 | +- Check that destination name matches exactly or position is within threshold |
| 184 | +- Try manual `-deliver` command as fallback |
| 185 | +
|
| 186 | +### F10 menu not showing |
| 187 | +- Player must be in a valid slot (not spectator) |
| 188 | +- Check that player's group_id is valid |
| 189 | +- Verify the mission plugin's menu system is working |
0 commit comments