kiosko-plugin-gaming 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Loksly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,154 @@
1
- # Temporary Holding Version
1
+ # kiosko-plugin-gaming
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Game FPS, 1 % low and frame times (MangoHud, PresentMon), and the cooling: fans, pumps and coolant (liquidctl, lm-sensors, LibreHardwareMonitor).
4
+
5
+ A plugin for [Kiosko](https://github.com/kiosko-lcd/kiosko), the widget mosaic for small USB LCD panels. **Optional:** Kiosko doesn't install it.
6
+
7
+ ![Game FPS](docs/fps.png)
8
+
9
+ ## Install
10
+
11
+ In Kiosko, **Plugins → Install from npm** → `kiosko-plugin-gaming`, then restart Kiosko. Or from a terminal:
12
+
13
+ ```sh
14
+ npm install --prefix ~/.config/kiosko/plugins kiosko-plugin-gaming
15
+ ```
16
+
17
+ (macOS: `~/Library/Application Support/Kiosko/plugins`, Windows: `%APPDATA%\Kiosko\plugins`.)
18
+
19
+ ## Requirements
20
+
21
+ Each source works with whatever tools it finds; set up the ones you have.
22
+
23
+ **FPS and frame times** (`gaming/frames`), only while a game runs:
24
+
25
+ - **Linux: [MangoHud](https://github.com/flightlessmango/MangoHud)** writing its
26
+ CSV log as it plays (a version that writes the log while recording). In
27
+ `~/.config/MangoHud/MangoHud.conf`:
28
+
29
+ ```ini
30
+ output_folder=/home/you/mangohud
31
+ autostart_log=1
32
+ log_interval=0
33
+ ```
34
+
35
+ and the same folder in the source's `mangohudFolder` (default `~/mangohud`).
36
+ Start games with `mangohud %command%` (Steam) or `MANGOHUD=1`. The newest log
37
+ in the folder is followed as it grows; a few seconds without new frames
38
+ means the game is gone. MangoHud's own summary files are ignored.
39
+ - **Windows: [PresentMon](https://github.com/GameTechDev/PresentMon) 2.x** (the
40
+ console program) on the `PATH` or at the path in `presentmon`. Kiosko runs it
41
+ with its CSV on stdout while a widget needs it (`--output_stdout
42
+ --no_console_stats --stop_existing_session --session_name KioskoGaming
43
+ --exclude dwm.exe`). It needs an administrator, or a user in the *Performance
44
+ Log Users* group. The game is the program presenting the most frames. Or set
45
+ `presentmonCsv` to a CSV PresentMon is already writing (`--output_file`).
46
+
47
+ The average FPS and the 1 % low (the average FPS of the slowest 1 % of frames)
48
+ are taken over the last `windowMs` of play (30 s).
49
+
50
+ **Fans, pumps and coolant** (`gaming/cooling`), any that answer, merged:
51
+
52
+ - **[liquidctl](https://github.com/liquidctl/liquidctl)** (Linux, macOS,
53
+ Windows): AIO coolers and Corsair / NZXT controllers, `liquidctl status
54
+ --json`. Some devices need `liquidctl initialize all` once after boot, and on
55
+ Linux the udev rules that let your user reach the device.
56
+ - **lm-sensors** (Linux): `sensors -j`, the motherboard fan headers and the
57
+ kernel drivers of AIOs (`nzxt-kraken3`, `aquacomputer_d5next`…).
58
+ - **[LibreHardwareMonitor](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor)**
59
+ (Windows): turn on *Options → Remote Web Server → Run*; its `/data.json` on
60
+ `http://localhost:8085` is read by default on Windows (`lhmUrl` for another
61
+ host or port).
62
+
63
+ A pump is a channel whose name says *pump*; the coolant, a temperature that
64
+ says *liquid*, *water* or *coolant* (or any of an AIO's own). Stopped fans
65
+ (empty headers) are hidden by default; a stopped pump never is.
66
+
67
+ ## What it does on your machine
68
+
69
+ - **Internet**: contacts `localhost`, the ones you set in its options.
70
+ - **Runs**: `liquidctl`, `sensors`, `PresentMon`.
71
+ - **Reads**: `~/mangohud`.
72
+ - **Devices**: usb.
73
+
74
+ ## Widgets
75
+
76
+ ### Game FPS — `gaming/fps`
77
+
78
+ The average FPS, big, the 1 % low and a frame-time curve where every stutter shows. Hidden while no game runs.
79
+
80
+ ![Game FPS](docs/fps.png)
81
+
82
+ Uses: `gaming/frames`.
83
+
84
+ | Option | Type | Default | |
85
+ |---|---|---|---|
86
+ | `fpsWarn` | number | `50` | Amber under. FPS. Frames slower than this are amber in the curve. |
87
+ | `fpsAlert` | number | `30` | Red under. FPS. Frames slower than this are red in the curve: the stutters you feel. |
88
+ | `frames` | number | `300` | Frames in the curve |
89
+ | `showGame` | boolean | `true` | Show the game's name |
90
+
91
+ ### Cooling — `gaming/cooling`
92
+
93
+ Coolant temperature, pump and fan speeds with their duty. Dim until the coolant warms up or a pump slows down.
94
+
95
+ ![Cooling](docs/cooling.png)
96
+
97
+ Uses: `gaming/cooling`.
98
+
99
+ | Option | Type | Default | |
100
+ |---|---|---|---|
101
+ | `tempWarn` | number | `40` | Amber coolant |
102
+ | `tempAlert` | number | `45` | Red coolant. Most AIOs are rated to about 60 °C; past 45 °C the loop is losing. The widget keeps the tile while it is past it. |
103
+ | `pumpWarn` | number | `800` | Amber pump under |
104
+ | `pumpAlert` | number | `300` | Red pump under. A pump that stops is a CPU about to throttle. The widget keeps the tile while one is under it. |
105
+ | `sensors` | list | `[]` | Sensors. Empty: all. Channel or device names, comma-separated: * matches anything, a leading ! leaves out (Pump, Fan*, !amdgpu). |
106
+ | `hideStopped` | boolean | `true` | Hide stopped fans. Empty headers read 0 rpm. A stopped pump is always shown. |
107
+
108
+ ## Page template
109
+
110
+ **Gaming**: the FPS widget, the cooling widget and a clock, on wide, square and tall panels (Editor → New page).
111
+
112
+ ## Data sources
113
+
114
+ ### Game frames — `gaming/frames`
115
+
116
+ FPS, 1 % low and frame times of the game being played, from MangoHud (Linux) or PresentMon (Windows). Only while a game runs. Followed live (once a second) while a widget uses it. Options are set once in Kiosko → Settings → Data sources.
117
+
118
+ | Option | Type | Default | |
119
+ |---|---|---|---|
120
+ | `backend` | `auto` \| `mangohud` \| `presentmon` | `"auto"` | Tool. auto: PresentMon on Windows, MangoHud elsewhere. |
121
+ | `mangohudFolder` | string | `"~/mangohud"` | MangoHud log folder. MangoHud's output_folder. In MangoHud.conf: output_folder=/home/you/mangohud, autostart_log=1 and log_interval=0 (every frame). The newest log there is followed while it grows. |
122
+ | `presentmon` | string | `"PresentMon"` | PresentMon program. PresentMon 2 (the console one), on the PATH or a full path. Run while the source runs, with its CSV on stdout. Needs an administrator or a member of Performance Log Users. Empty: don't run it. |
123
+ | `presentmonCsv` | string | `""` | PresentMon CSV file. Set, this file is followed while it grows (PresentMon --output_file) instead of running PresentMon. |
124
+ | `windowMs` | duration (ms) | `30000` | Average over. Of play, for the average FPS and the 1 % low. |
125
+ | `staleMs` | duration (ms) | `5000` | Game gone after. Without a new frame for this long, no game is running. |
126
+
127
+ ### Cooling — `gaming/cooling`
128
+
129
+ Fan and pump speeds, duty and coolant temperature, from liquidctl, lm-sensors (Linux) or LibreHardwareMonitor (Windows). Read every 3 s while a widget uses it. Options are set once in Kiosko → Settings → Data sources.
130
+
131
+ | Option | Type | Default | |
132
+ |---|---|---|---|
133
+ | `liquidctl` | string | `"liquidctl"` | liquidctl program. Runs liquidctl status --json: AIO coolers and Corsair / NZXT controllers. Initialize them once (liquidctl initialize all) after boot if your device asks for it. Empty: off. |
134
+ | `lmSensors` | string | `"sensors"` | lm-sensors program. Runs sensors -j (Linux): motherboard fan headers and the kernel drivers of AIOs. Empty: off. |
135
+ | `lhmUrl` | string | `""` | LibreHardwareMonitor web server. Its /data.json (Options → Remote Web Server → Run). Empty: http://localhost:8085 on Windows, off elsewhere. |
136
+
137
+ ## Development
138
+
139
+ ```sh
140
+ npm install
141
+ npm test # node:test
142
+ npm run check # TypeScript
143
+ npm run build # dist/index.js, what Kiosko loads
144
+ ```
145
+
146
+ To try it in a running Kiosko without publishing: `kiosko plugins link .` and restart Kiosko.
147
+
148
+ Working on Kiosko and its plugins together: clone them side by side
149
+ (`kiosko/` and `kiosko-plugins/kiosko-plugin-gaming/`) and run `npm install` in
150
+ `kiosko/`; its workspaces link every plugin found in `../kiosko-plugins`.
151
+
152
+ ## License
153
+
154
+ MIT