Skip to content

Commit ed23894

Browse files
karel26karel26
authored
Merge pull request #97 from engines-wafu/feature/logbook-plugin
Add logbook plugin for pilot/squadron management
2 parents 337cdd8 + 3fc7053 commit ed23894

File tree

12 files changed

+5389
-0
lines changed

12 files changed

+5389
-0
lines changed

‎plugins/logbook/README.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Logbook Plugin
2+
3+
A comprehensive pilot logbook and squadron management plugin for DCSServerBot. Provides military-style record keeping for virtual squadrons including flight statistics, qualifications, awards, and flight plans.
4+
5+
## Features
6+
7+
- **Pilot Statistics**: View flight hours, kills, deaths, takeoffs, landings from existing DCSServerBot data
8+
- **Squadron Management**: Create squadrons with CO/XO hierarchy, assign members with ranks and positions
9+
- **Qualifications**: Define qualifications with optional expiration, auto-grant based on requirements
10+
- **Awards**: Create awards with custom ribbon colors, generate ribbon rack images
11+
- **Flight Plans**: File, track, and manage flight plans with status workflow
12+
- **Stores Requests**: Submit and track logistics/stores requests with approval workflow
13+
14+
## Requirements
15+
16+
- **userstats plugin** must be enabled (provides the `statistics` table used for pilot stats)
17+
- **greenieboard plugin** (optional) - enables carrier landing counts for auto-grant qualifications
18+
19+
## Installation
20+
21+
1. Add `logbook` to `opt_plugins` in your `config/main.yaml`:
22+
```yaml
23+
opt_plugins:
24+
- logbook
25+
```
26+
27+
2. Restart DCSServerBot - the database tables will be created automatically
28+
29+
3. (Optional) Configure the plugin in `config/plugins/logbook.yaml`
30+
31+
## Configuration
32+
33+
```yaml
34+
# config/plugins/logbook.yaml
35+
DEFAULT:
36+
auto_qualifications: true # Enable auto-grant qualifications on requirements met
37+
```
38+
39+
## Commands
40+
41+
### Logbook Commands (`/logbook`)
42+
43+
| Command | Description | Role |
44+
|---------|-------------|------|
45+
| `/logbook stats [user]` | Show pilot flight statistics | DCS |
46+
47+
### Squadron Commands (`/logbook squadron`)
48+
49+
| Command | Description | Role |
50+
|---------|-------------|------|
51+
| `/logbook squadron list` | List all squadrons | DCS |
52+
| `/logbook squadron info <squadron>` | Show squadron details | DCS |
53+
| `/logbook squadron roster <squadron>` | Show squadron roster with stats | DCS |
54+
| `/logbook squadron create <name> [abbreviation] [description]` | Create a new squadron | DCS Admin |
55+
| `/logbook squadron delete <squadron>` | Delete a squadron | DCS Admin |
56+
| `/logbook squadron assign <squadron> <user> [rank] [position]` | Assign pilot to squadron | DCS Admin |
57+
| `/logbook squadron remove <squadron> <member>` | Remove pilot from squadron | DCS Admin |
58+
| `/logbook squadron promote <squadron> <member> <rank>` | Update member's rank | DCS Admin |
59+
| `/logbook squadron setco <squadron> <member>` | Set Commanding Officer | DCS Admin |
60+
| `/logbook squadron setxo <squadron> <member>` | Set Executive Officer | DCS Admin |
61+
62+
### Qualification Commands (`/qualification`)
63+
64+
| Command | Description | Role |
65+
|---------|-------------|------|
66+
| `/qualification list [user]` | List qualifications or pilot's qualifications | DCS |
67+
| `/qualification info <qualification>` | Show qualification details | DCS |
68+
| `/qualification create <name> [description] [aircraft_type] [valid_days]` | Create qualification | DCS Admin |
69+
| `/qualification delete <qualification>` | Delete qualification | DCS Admin |
70+
| `/qualification grant <user> <qualification>` | Grant qualification to pilot | DCS Admin |
71+
| `/qualification revoke <user> <qualification>` | Revoke qualification from pilot | DCS Admin |
72+
| `/qualification refresh <user> <qualification>` | Refresh expiration date | DCS Admin |
73+
| `/qualification expiring [days]` | List qualifications expiring soon | DCS Admin |
74+
75+
### Award Commands (`/award`)
76+
77+
| Command | Description | Role |
78+
|---------|-------------|------|
79+
| `/award list [user]` | List awards or pilot's awards | DCS |
80+
| `/award info <award>` | Show award details | DCS |
81+
| `/award ribbon [user]` | Generate ribbon rack image | DCS |
82+
| `/award create <name> [description] [ribbon_colors] [image_url]` | Create award | DCS Admin |
83+
| `/award delete <award>` | Delete award | DCS Admin |
84+
| `/award grant <user> <award> [citation]` | Grant award to pilot | DCS Admin |
85+
| `/award revoke <user> <award>` | Revoke award from pilot | DCS Admin |
86+
87+
### Flight Plan Commands (`/flightplan`)
88+
89+
| Command | Description | Role |
90+
|---------|-------------|------|
91+
| `/flightplan file <callsign> <aircraft_type> <departure> <destination> [alternate] [route] [remarks]` | File a flight plan | DCS |
92+
| `/flightplan view <plan>` | View flight plan details | DCS |
93+
| `/flightplan list [status] [user]` | List flight plans | DCS |
94+
| `/flightplan activate <plan>` | Activate a filed plan | DCS |
95+
| `/flightplan complete <plan>` | Mark plan as completed | DCS |
96+
| `/flightplan cancel <plan>` | Cancel a flight plan | DCS |
97+
98+
### Stores Request Commands (`/stores`)
99+
100+
| Command | Description | Role |
101+
|---------|-------------|------|
102+
| `/stores request <items>` | Submit a stores/logistics request | DCS |
103+
| `/stores list [status] [user]` | List stores requests | DCS |
104+
| `/stores view <request>` | View request details | DCS |
105+
| `/stores approve <request>` | Approve a stores request | DCS Admin |
106+
| `/stores deny <request> [reason]` | Deny a stores request | DCS Admin |
107+
108+
## Auto-Grant Qualifications
109+
110+
Qualifications can be automatically granted when pilots meet specified requirements. Define requirements as JSON when creating a qualification:
111+
112+
```
113+
/qualification create name:"Carrier Qualified" valid_days:90
114+
```
115+
116+
Then set requirements in the database `logbook_qualifications.requirements` column:
117+
```json
118+
{"flight_hours": 50, "carrier_landings": 10}
119+
```
120+
121+
Supported requirement keys:
122+
- `flight_hours` - Total flight hours
123+
- `total_kills` - Total kills
124+
- `deaths` - Total deaths (use `deaths_max` for maximum)
125+
- `takeoffs` - Total takeoffs
126+
- `landings` - Total landings
127+
- `carrier_landings` - Carrier landings (requires greenieboard plugin)
128+
129+
## Ribbon Generation
130+
131+
Awards can have custom ribbon colors defined as a JSON array of hex colors:
132+
```
133+
/award create name:"Distinguished Flying Cross" ribbon_colors:'["#0000FF", "#FFFFFF", "#FF0000"]'
134+
```
135+
136+
Use `/award ribbon` to generate a ribbon rack image showing all of a pilot's awards.
137+
138+
**Note**: Ribbon generation requires PIL (Pillow), numpy, and matplotlib libraries.
139+
140+
## Migration from dcs_server_logbook
141+
142+
A migration script is included for importing data from the Joint Strike Wing's dcs_server_logbook:
143+
144+
```bash
145+
python plugins/logbook/scripts/migrate_from_dcs_server_logbook.py \
146+
--sqlite-path /path/to/mayfly.db \
147+
--slmod-path /path/to/SlmodStats.lua \
148+
--postgres-url "postgres://user:pass@host:5432/db"
149+
```
150+
151+
Options:
152+
- `--dry-run` - Preview migration without making changes
153+
- `--verbose` - Show detailed progress
154+
155+
The migration preserves all historical flight hours using a `GREATEST()` function in the stats view, ensuring pilots never see fewer hours after migration.
156+
157+
## Database Schema
158+
159+
The plugin creates the following tables:
160+
- `logbook_squadrons` - Squadron definitions
161+
- `logbook_squadron_members` - Pilot-squadron assignments
162+
- `logbook_qualifications` - Qualification definitions
163+
- `logbook_pilot_qualifications` - Granted qualifications
164+
- `logbook_awards` - Award definitions
165+
- `logbook_pilot_awards` - Granted awards
166+
- `logbook_flight_plans` - Filed flight plans
167+
- `logbook_stores_requests` - Stores/logistics requests
168+
- `logbook_historical_hours` - Imported historical flight time
169+
170+
And one view:
171+
- `pilot_logbook_stats` - Aggregated pilot statistics

‎plugins/logbook/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
from .version import __version__

0 commit comments

Comments
 (0)