Skip to content

FishPort-Net/FPBrowser

BranchesTags

Repository files navigation

FPBrowser

在 Minecraft Display Entity 上渲染网页的 Fabric 客户端 Mod

Minecraft Version Fabric MCEF License

概述

FPBrowser 是一个强大的 Fabric 客户端 Mod，允许在 Minecraft 的 Display Entity 上渲染实时网页内容。基于 MCEF (Minecraft Chromium Embedded Framework)，为玩家提供沉浸式的网页浏览体验。

核心特性

  • 真实网页渲染 - 基于 Chromium 引擎，支持现代 Web 标准
  • 交互式操作 - 鼠标点击、键盘输入、滚轮滚动等完整交互支持
  • 3D 空间音频 - 根据玩家位置和角度的智能音量调节
  • 权限管理 - 完善的权限系统，支持所有者、编辑者、控制者角色
  • 性能优化 - 可配置的渲染半径、最大屏幕数、帧率限制等
  • 安全隔离 - Cookie 数据本地存储，服务端控制 URL 下发

架构设计

客户端-服务端通信

┌──────────────────────────────────────────────────────────────────┐
│                         客户端 (Fabric Mod)                        │
│  ┌──────────────────┐         ┌──────────────────┐               │
│  │ Display Entity   │         │  WebView 渲染    │               │
│  │  扫描与发现       │◄───────►│   (MCEF/Chromium)│               │
│  └──────────────────┘         └──────────────────┘               │
│           │                             │                         │
│           │ STATE_QUERY                 │ EVENT_REQ               │
│           ▼                             ▼                         │
└───────────┼─────────────────────────────┼─────────────────────────┘
            │                             │
            │        fpbrowser:bridge     │
            │      (自定义通信信道)         │
            │                             │
└───────────┼─────────────────────────────┼─────────────────────────┐
            │                             │                         │
            ▼                             ▼                         │
│  ┌──────────────────┐         ┌──────────────────┐               │
│  │  状态管理器       │         │  事件处理器       │               │
│  │  (URL/权限/性能)  │         │  (鉴权/限速)      │               │
│  └──────────────────┘         └──────────────────┘               │
│                        服务端 (Paper/Spigot 插件)                   │
└──────────────────────────────────────────────────────────────────┘

关键设计原则

  • 职责分离 - 客户端负责渲染，服务端负责逻辑与权限
  • 安全优先 - URL 由服务端下发，客户端无法任意加载
  • 性能可控 - 多层性能参数配置，适应不同硬件环境
  • 隐私保护 - 浏览器数据永不离开客户端

功能详解

1. 网页渲染

  • 显示平面 - 网页渲染在 Display Entity 位置的四边形平面上
  • 完整变换矩阵 - 支持任意角度旋转（优先读取 transformation matrix）
  • 单面可见 - 屏幕仅从正面（+Z 方向）可见，背面透明
  • 智能偏移 - 根据 Display 类型自动调整 z-offset：
    • Block: 0.52
    • Item: 0.08
    • Text: 0.02

2. 屏幕操作模式 (Focus Mode)

按 F6（可在设置中重新绑定）进入屏幕操作模式：

操作 效果
F6（对准屏幕） 进入操作模式
F6 / ESC 退出操作模式
鼠标移动 光标在屏幕上移动（射线投射）
鼠标点击 发送点击事件到网页
鼠标滚轮 发送滚动事件到网页
键盘输入 发送到网页（支持文本输入）

操作模式特性：

  • 游戏画面不被遮挡，完全透明叠加
  • 十字准心颜色指示：
    • 🟢 绿色 = 光标在屏幕上
    • 🔴 红色 = 光标偏离屏幕
  • 精确的射线投射算法，确保鼠标坐标准确映射

3. 3D 音频锥

网页音频根据玩家位置智能调节：

      正前方 90°（全音量）
           │
     ╱─────┴─────╲
    ╱  音量高    ╲
   ╱             ╲
 屏幕 ─────────────► 正前方 (+Z)
   ╲             ╱
    ╲  线性淡出  ╱  (90°~120°)
     ╲─────┬─────╱
          120°（静音）

音频参数：

  • 正面半球：正前方 90° 内全音量
  • 侧后方衰减：90°~120° 线性淡出
  • 正后方：>120° 完全静音
  • 最大距离：48 格
  • 音量计算：volume = angleFactor × distanceFactor
  • 量化步长：0.05（避免频繁更新）

4. 点击交互

无需进入操作模式，准星对准屏幕时：

  • 左键点击 → 上报 attack_click 事件
  • 右键点击 → 上报 use_click 事件

事件经服务端鉴权后，下发执行命令到客户端浏览器。

5. 权限系统

完整的权限体系，支持细粒度访问控制：

权限类型 说明
所有者 (Owner) 完全控制权限，可转移所有权
编辑者 (Editor) 可修改 URL、性能参数
控制者 (Controller) 可与屏幕交互
公开 (Public) 所有人可查看/控制

客户端命令

所有命令前缀：/fpbrowser

命令 参数 说明
reload - 重新加载所有浏览器实例
maxviews <1-64> 设置同时显示的最大屏幕数
radius <8-512> 设置加载半径（格）
volume [0-100] 设置主音量百分比
cleardata <target> 清除浏览器数据（all/域名/通配符）

示例：

/fpbrowser maxviews 32        # 设置最大显示 32 个屏幕
/fpbrowser radius 128         # 设置加载半径为 128 格
/fpbrowser volume 75          # 设置音量为 75%
/fpbrowser cleardata all      # 清除所有浏览器数据
/fpbrowser cleardata *.example.com  # 清除特定域名的数据

调试模式： 通过 JVM 参数启用：-Dfpbrowser.debug=true

服务端命令

所有命令前缀：/webdisplay（需要 FPBrowserManager 插件）

实例管理

命令 参数 说明
create `<text item
delete <target> 删除屏幕实例
enable ` <true false>`
list - 列出所有屏幕
info <target> 查看屏幕详细信息

内容设置

命令 参数 说明
seturl <target> <url> 设置屏幕 URL
setjson <target> <json> 设置 JSON 负载
setorigin <target> 将原点设置为当前位置

性能调整

命令 参数 说明
perf <target> <maxFps> <maxDist> <maxBrowsers> 性能参数
size <target> <width10x> <height10x> 显示平面大小（格）

权限管理

命令 参数 说明
setowner <target> <player> 设置所有者
public <target> <view> <control> 设置公开权限
allowedit <target> <player> 添加编辑者
allowcontrol <target> <player> 添加控制者
remove <target> <player> 移除权限
setperm <target> <preset> 应用权限预设

示例：

/webdisplay create text        # 在当前位置创建文本显示
/webdisplay seturl @p https://example.com  # 设置当前屏幕 URL
/webdisplay perf @p 30 64 8    # 设置性能参数
/webdisplay public @p true false  # 允许所有人查看，但不可控制
/webdisplay allowedit @p Steve  # 允许 Steve 编辑

按键绑定

按键 功能 分类
F6 切换屏幕操作模式 FPBrowser

可在 Minecraft 设置 → 控制 → 按键绑定 中修改。

配置参数

客户端配置

参数 默认值 范围 说明
enabled true - 总开关
maxViews 24 1-64 同时渲染的最大屏幕数
loadRadius 256.0 8-512 发现屏幕的半径（格）

服务端下发的每屏幕参数

参数 默认值 说明
maxFps 20 浏览器最大帧率
maxDistance 48 渲染最大距离（格）
maxBrowsersPerPlayer 4 每玩家最大浏览器数
planeWidth 6.0 显示平面宽度（格，最大48）
planeHeight 3.375 显示平面高度（格，最大48）
textureWidth 1920 纹理分辨率宽
textureHeight 1080 纹理分辨率高

隐私与数据

数据本地化

  • Cookie 永不离开客户端 - 所有浏览数据存储在本地
  • 支持清理 - 通过命令清除浏览器数据：
    • all - 清除全部数据
    • example.com - 清除特定域名
    • *.example.com - 清除通配符域名

清理范围

  • Cookie
  • localStorage
  • sessionStorage
  • IndexedDB
  • 缓存数据

构建

前置要求

  • JDK 21+
  • Gradle 8.0+

构建步骤

# 克隆仓库
git clone https://github.com/FishPort-Net/FPBrowser.git
cd FPBrowser

# 构建
./gradlew build

# 输出位置
# build/libs/fpbrowser-{version}.jar

安装

客户端安装

  1. 安装 Fabric Loader
  2. 安装 Fabric API
  3. 安装 MCEF 2.1.6
  4. 将 FPBrowser jar 文件放入 mods 文件夹

服务端安装

  1. 安装 Paper 或 Spigot
  2. 安装 FPBrowserManager 插件
  3. 重启服务器

依赖

依赖 版本 说明
Minecraft 1.21.4 目标游戏版本
Fabric Loader 0.16.14+ Mod 加载器
Fabric API 0.119.4+ Fabric API
MCEF 2.1.6-1.21.4 Minecraft Chromium Embedded Framework

技术亮点

渲染优化

  • 视锥体剔除 - 只渲染视野内的屏幕
  • 距离剔除 - 超过配置距离的屏幕不渲染
  • LOD 系统 - 根据距离动态调整渲染质量
  • 纹理缓存 - 智能纹理缓存策略

网络优化

  • 增量更新 - 只同步变化的屏幕状态
  • 批量传输 - 合并小数据包减少网络开销
  • 压缩传输 - 使用 GZIP 压缩大数据包

内存优化

  • 实例池 - 复用浏览器实例
  • 智能卸载 - 超出范围的屏幕自动卸载
  • 资源限制 - 严格限制同时加载的屏幕数量

故障排除

常见问题

Q: 屏幕显示空白或无法加载

  • 检查服务端是否已设置 URL
  • 确认客户端网络连接正常
  • 查看 logs/fpbrowser.log 获取详细错误信息

Q: 操作模式无法进入

  • 确保准星对准屏幕
  • 检查 F6 按键绑定是否被其他 Mod 占用
  • 确认屏幕未被服务端禁用

Q: 音频无法播放

  • 检查主音量设置：/fpbrowser volume
  • 确认玩家在音频锥形范围内
  • 验证网页音频元素格式支持

Q: 性能问题/卡顿

  • 减少最大屏幕数：/fpbrowser maxviews 16
  • 降低加载半径：/fpbrowser radius 128
  • 调整帧率限制：/webdisplay perf @p 15 32 4

调试模式

启用调试模式以获取详细日志：

启动参数添加: -Dfpbrowser.debug=true

调试日志将输出到：

  • 控制台
  • logs/fpbrowser-debug.log

开发文档

详细的技术文档请查看：

贡献

欢迎贡献！请遵循以下步骤：

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

代码规范

  • 遵循 Google Java Style Guide
  • 添加适当的注释和文档
  • 确保所有测试通过
  • 更新相关文档

致谢

本项目的开发受到以下项目的启发和帮助：

  • webmapview - 提供了在 Minecraft 中渲染网页的参考实现
  • xingwangzhe - 感谢在 webmapview 项目中的开创性工作
  • MCEF - 感谢提供的 Minecraft Chromium Embedded Framework 集成
  • Fabric - 感谢 Fabric 团队的优秀 Mod 开发框架
  • PaperMC - 感谢 Paper 团队的高性能服务端实现

许可证

本项目采用 Apache License 2.0 - 详见 LICENSE 文件

Copyright 2025 FishPort Team

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

联系方式

Made with ❤️ by FishPort Team

官网 • Discord • Wiki

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages