Web 游戏操控 SDK--云游戏-火山引擎

文档中心

导航

Web 游戏操控 SDK

最近更新时间：2025.01.20 15:23:37首次发布时间：2022.08.30 11:15:37

SDK 简介

在用户通过 PC 端使用 Web 体验云手游的场景下，需要将用户的鼠标操作和键盘操作映射为手游的 Touch 和手势滑动事件。火山引擎云游戏操控 SDK 与 veGame Web SDK 集成使用（业务方需要根据宿主是否是 Web 选择集成云游戏操控 SDK），提供 Web 端键鼠映射解决方案。其核心功能包括：

支持常用的游戏操控行为（参考键位种类说明）
提供游戏默认键位配置文件，可直接使用（如有特殊需求，可联系火山引擎云游戏服务对接人员）
当前版本提供键位配置编辑器固定 UI 样式，支持快速集成接入

有关 veGame Web SDK 的接入说明，参考 Web SDK 接口说明。

SDK 接入说明

本文档描述了云游戏操控 SDK 的使用说明，方便您快速接入。

键位配置定义

按键位置以及内容通过 JSON 数据进行描述，根据配置信息在控制器上生成键位。

字段	类型	说明
gameId	String	游戏 ID
name	String	键位配置方案名称
keysConfig	String	键位配置信息（当前版本为游戏的默认键位配置）

读入配置

云游戏操控 SDK 支持读入游戏键位配置功能。具体流程如下：

业务方调用服务端 “游戏详情查询” 接口（DetailGame），根据游戏 ID（gameid）从云游戏服务端拉取游戏默认键位配置。
云游戏操控 SDK 读入拉取的游戏键位配置，生成键位 UI，用户即可通过鼠标和键盘进行游戏操作。

接入指南

`<script>` 标签引入

参考示例：

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>火山引擎云游戏操控SDK</title>
        <style>
            #player {
                width: 100vh;
                height: 100vh;
                overflow: hidden;
            }
        </style>
    </head>
    <body>   
        <div id="player"></div> 
    </body>
    <script src="veController.umd.min.js"></script>
    <script src="veGameSDK.umd.min.js"></script>
    <script type="text/javascript">
        // 拉取游戏默认配置
        const keysConfig = await getGameKeysConfig(query)
        let controller = null
        const veGame = new veGameSDK({
            ...params,
            domId: "player"
        })
        veGame.start(startConfig).then((res) => {
            // 初始化游戏操控SDK
            controller = new veController(veGame, res.width, res.height)
            // 渲染键位DOM
            controller.render(keysConfig)
        })
    </script>
</html>

配合脚手架工具模块化引入

参考示例：

import ByteplayController from '<your loacal path>/veController.js'
import veGame from '<your local path>/veGame.js'
// 拉取游戏默认配置
const keysConfig = await getGameKeysConfig(query)
// 初始化veGameSDK
const veGame = new veGameSDK({
    ...params,
    domId: 'player'
})
let controller = null
veGame.start(startConfig).then((res) => {
    // 初始化游戏操控SDK
    controller = new veController(veGame, res.width, res.height)
    // 渲染键位DOM
    controller.render(keysConfig)
})

游戏内键盘操作示例：

键位种类说明

键位类别	键位描述
普通点击	通过单坐标点映射键位进行设置，模拟触屏和鼠标单次点击效果，发送一次鼠标事件就代表一次点击
连击（指定频率）	模拟触屏和鼠标连击效果，长按可以持续攻击，不必频繁敲击键盘；可以设置连击频次，n次/秒
准星/鼠标移动视角	模拟视角转动和瞄准效果，可以自定义生效键用来锁定/解锁准星：准星锁定状态时，隐藏鼠标光标，鼠标的移动带动准星的移动和游戏中视角的变化准星解锁状态时，显示鼠标光标，不随着鼠标光标移动而移动，鼠标光标可以点击其他按键支持设置准星的灵敏度，灵敏度是个0-100%的百分比数值
攻击/开火	模拟点击攻击按钮或鼠标左键触发开火效果，一般需要配合准星键位使用
智能（自定义）施法	由于某些游戏的技能是需要指定方向才能释放的，使用该键位只需按下智能施法快捷键，控制技能释放到鼠标所指定的方向（具体每个技能键的施法方式会根据游戏角色选择而变化，因此要保证技能键与游戏内技能位置对准）
键盘移动视角	模拟触碰和滑动手势，设置键位进行上下左右滑动调整视角，自定义键位模拟行走到不同方向的效果：可以设置滑动灵敏度可以使用↑←↓→方向键或其他键位
键盘行走	模拟触碰和滑动手势，操控轮盘控制角色行走：可以设置 WASD，也可以设置 ↑←↓→ 支持多个方向键同时按下支持奔跑/行走模式（配合Shift键，Shift减速）
右键行走	可以通过行走方向轮，实现点击鼠标右键就可以控制行走位置（需要游戏支持）
缩放	支持 Ctrl+鼠标滚轮实现游戏画面缩放（需要游戏支持）

接口说明

云游戏操控 SDK 提供的接口和详细说明如下：

初始化控制器实例

描述：透传 veGame SDK 生成的实例以及 veGame SDK start() 接口返回的游戏画面的宽度和高度，初始化控制器实例。

入参说明：

参数名	类型	默认值	是否必选	描述
veGame	Object	null	是	veGame SDK 生成的实例引用
width	Number	null	是	游戏画面的宽度，由 veGame SDK `start()` 接口返回
height	Number	null	是	游戏画面的高度，由 veGame SDK `start()` 接口返回

返回值：Controller 实例

示例：

const veGame = new veGameSDK(params)
let controller = null
veGame.start(startConfig).then((res) => {
    controller = new veController(veGame, res.width, res.height)
})

生成控制器 render

描述：渲染控制器的 DOM，提供键鼠映射的能力。