一段JavaScript搞定自动平铺:PartyDeck的KWin分屏脚本设计思路

原创2026-10-26 22:34:08234 阅读

一段JavaScript搞定自动平铺:PartyDeck的KWin分屏脚本设计思路

PartyDeck 是一款面向 Linux / SteamOS 的分屏游戏启动器,最多可在单台主机上同时运行 4 个游戏实例并自动平铺到屏幕上。而实现"窗口自动平铺"的,是一段不到 130 行的 JavaScript 分屏脚本。本文带你拆解这份 splitscreen_kwin.js 的设计思路,看看它如何用"查表 + 事件监听"把多窗口摆放这件事做得既简单又稳定。

🎮 先看效果:一个屏幕,多人同玩

PartyDeck 分屏实机效果:同一显示器上自动平铺两个游戏窗口

上图就是 PartyDeck 自动平铺后的画面:两个游戏实例各占屏幕一半,窗口无缝拼接、无边框。下面是它的分屏游戏启动器界面,负责管理多个游戏实例:

PartyDeck 分屏游戏启动器界面:左侧为游戏列表,右侧显示当前游戏的分屏配置

一、核心思路:用"查表"代替复杂计算

脚本开头就是四张"布局表"(res/splitscreen_kwin.js),按玩家数量索引每个窗口的位置和尺寸(均为相对屏幕的比例值):

玩家数 平铺布局
1 整屏独占
2 上下各占 1/2
3 顶部整宽 1/2 + 底部左右各 1/2
4 2×2 四等分

以 2 人模式为例,查表得到的 x 偏移是 [0, 0]、y 偏移是 [0, 0.5]、高度各为 0.5——正好上下对半切。

💡 为什么用查表?玩家数只有 1~4 种情况,穷举所有布局比写动态分割算法更直观,也更不容易出错。

PartyDeck 还内置了另一份 splitscreen_kwin_vertical.js,把方向反过来:2 人时左右并排、3 人时呈"L"形(左侧整列 + 右侧上下两格)。

二、如何认出"游戏窗口"?靠 gamescope 身份

脚本并不直接找游戏,而是找承载游戏的 gamescope 窗口(getGamescopeClients()):

if (
  allClients[i].resourceClass == "gamescope" ||
  allClients[i].resourceClass == "gamescope-kbm"
) {
  gamescopeClients.push(allClients[i]);
}

每个游戏实例都由 gamescope 包裹成一个独立窗口(启动参数见 src/launch.rs),resourceClass 是它的固定标识。按这个标识过滤,脚本就能准确锁定所有参与分屏的游戏,不会误伤其他窗口。

三、平铺算法:给每个窗口算出精确坐标

拿到全部 gamescope 窗口后,gamescopeSplitscreen() 对每个窗口做三件事:

  1. 算坐标:用窗口所在显示器的几何信息 + 布局表,算出目标位置:
gamescopeClients[i].frameGeometry = {
  x: monitorX + x[playerCount][playerIndex] * monitorWidth,
  y: monitorY + y[playerCount][playerIndex] * monitorHeight,
  width: monitorWidth * width[playerCount][playerIndex],
  height: monitorHeight * height[playerCount][playerIndex],
};
  1. 去边框:noBorder = true,保证多窗口无缝拼接;
  2. 多屏支持:用 Map 记录每台显示器上已有几个玩家(res/splitscreen_kwin.js),各显示器的实例独立平铺,互不干扰。

最后调用 gamescopeAboveBelow():当前激活的游戏窗口置顶,其余置后——玩家切到哪个画面,哪个窗口就浮在最上面。

四、自动触发:事件监听 + 100ms 延时兜底

脚本无需手动运行,它监听了三个 KWin 事件(res/splitscreen_kwin.js):

事件 触发动作
windowAdded 重新平铺
windowRemoved 重新平铺(某实例退出时自动补位)
windowActivated 刷新窗口层级

注意这些事件都先经过一个 100ms 的 QTimer 延时(gamescopeSplitscreenDelayed())再执行。这是因为窗口刚出现时位置信息还没稳定,稍等一下再计算坐标,平铺结果才可靠。

五、PartyDeck 如何加载这段脚本?

脚本本体只是资源文件,真正"启动"它的是 PartyDeck 的 Rust 代码:

  • 通过 D-Bus 调用 KWin 的 org.kde.kwin.Scripting 接口完成 loadScript + start(kwin_dbus_start_script());
  • 根据 vertical_two_player 选项决定加载横版还是竖版脚本(src/launch.rs);
  • 游戏全部退出时再调用 unloadScript 卸载脚本,把窗口状态还给桌面。

对应开关在 PartyDeck 设置中为 "(KDE) Resize instances to fit the screen"(src/app/app_pages.rs),配置项 enable_kwin_script 定义在 src/app/config.rs。需要提醒:该脚本要求 KDE Plasma 6.0 或更新版本;如果使用其他桌面环境,建议关闭它并手动摆放窗口(详见 README.md)。

小结

设计点 做法 好处
布局计算 1~4 人布局查表 简单直观,无算法边界 bug
窗口识别 按 resourceClass 过滤 精准锁定游戏窗口
触发机制 窗口事件 + 100ms 延时 自动重排,结果稳定
窗口层级 激活窗口置顶 多画面自由切换
加载方式 D-Bus 调用 KWin 脚本接口 无需常驻进程

一段不到 130 行的 JavaScript,配合 KWin 脚本接口,就实现了"窗口出现即自动平铺、退出即自动补位"的分屏体验——这正是 PartyDeck 能让多人同屏开黑的底层秘密之一。

登录后查看全文
partydeck