SuperMarioVRC

If you enjoy this project, please consider giving it a Star. Your support means a lot to me.

如果你喜欢这个项目，欢迎点个 Star。你的支持对我来说非常重要。

Game Preview

https://x.com/qychui/status/2079112705274003566

https://x.com/qychui/status/2066423783314059610

English | 中文

English

Project Overview

SuperMarioVRC is an unofficial fan-made project built with Unity, VRChat SDK Worlds, and UdonSharp. It recreates the levels, controls, and game flow of the Famicom / NES version of Super Mario Bros. in VRChat.

The project supports both desktop and VR controls, with multiplayer synchronization for game state, player movement, and key gameplay events.

Main Features

• Includes World 1-1 through World 8-4, along with underground, underwater, sky, and hidden areas.
• Supports single-player mode and an alternating two-player mode featuring Mario and Luigi.
• Includes movement, jumping, swimming, pipes, vines, checkpoints, castle mazes, and complete level-clear sequences.
• Includes coins, Super Mushrooms, Fire Flowers, Starmen, fireballs, familiar enemies, and bosses.
• Supports desktop keyboard controls and VRChat input events.
• Supports synchronized multiplayer state, late joining, and gameplay ownership transfers.
• Provides a core game Prefab, a retro TV version, and the optional Bill Mode.

Requirements

Dependency	Version
Unity	2022.3.22f1
VRChat SDK Worlds	3.10.4
UdonSharp	Included with VRChat SDK Worlds

ALCOM or VRChat Creator Companion is recommended for creating and managing the Worlds project.

Installation

1. Create a Worlds project with ALCOM or VRChat Creator Companion.
2. Confirm that the Unity and VRChat SDK Worlds versions match the requirements above.
3. Download and import the SuperMarioVRC.unitypackage provided on the Releases page.
4. Wait for Unity to finish importing the assets and compiling the UdonSharp scripts.
5. Open Assets/SuperMario/Scenes/SuperMario.unity to view the sample scene, or add the required Prefabs to your own scene.

After importing the package, install TextMeshPro (TMP) to display the test panel and instructions correctly. If TMP has not been configured in the project, install TextMeshPro through Package Manager, then select Window > TextMeshPro > Import TMP Essential Resources.

Controls

Pick up the game controller before starting the game.

Action	Desktop	VR
Move / Navigate menus	Arrow keys	Left stick
Jump / Confirm	J	A
Run / Throw fireballs	K	RT

Desktop key bindings can be changed on the InputController component.

Main Prefabs

• Prefabs/SuperMario.prefab: Core game object without an external TV model.
• Prefabs/Retro TV Mario.prefab: Complete version with a retro TV presentation.
• Prefabs/Instruction Mario.prefab: Controls and usage instructions.
• Prefabs/GameTestPanel.prefab: Test panel for development and debugging.

Main objects inside SuperMario.prefab:

Object	Purpose
ScreenRoot, Screen, UI Manager	Display the game, HUD, title menu, and flow messages.
Controller	Provides the pickup controller, reads desktop and VR input, and requests gameplay ownership.
GameManager, LevelController	Manage game modes, score and lives, level transitions, the timer, camera, and clear sequences.
Player	Handles character movement, collision, animation, damage, and power-up states.
EntityManager, ObjectPoolManager, ScoreManager	Manage enemies, items, projectiles, object pools, and score popups.
SyncController, PlayerMotionSync, SyncPayloadCodec	Synchronize game state, key events, and player movement.
AudioManager, PaletteManager, TitleDemoController	Manage audio, visual palettes, and the title-screen demo.
BillDLC, GameTestPanel, GameRestartCanvas	Provide the optional mode, development tools, and game restart controls.

Creating a New Level

1. Find an existing level inside SuperMario.prefab and duplicate a similar World X-Y object as a template, such as an overworld, underground, underwater, or castle level.
2. Rename the level root and its Tilemaps. You can also use SuperMario > Tools > World X-Y Name Replace to update object names and HUD world numbers in bulk.
3. Configure the level number, palette, timer, level width, camera, spawn point, nextWorld, and other basic settings on WorldController.
4. Edit the main Tilemaps. Standard Tilemaps render the level, TerrainCollider defines solid terrain, InteractiveBlock places blocks, items, and goal markers, and Enemies places enemy and platform spawn markers.
5. Configure pipe entrances and exits, checkpoints, vines, goal walk targets, and any other special level mechanics as needed.
6. Select the level's WorldController and click Bake All Child Map Data to bake collision, interactive block, and enemy marker data for runtime use. You can also bake individual data sets through SuperMario > Level Bake Tool.
7. Add the new level to LevelController.worlds in the correct order, then verify the surrounding nextWorld, pipe target, and other transition references.
8. Save the Prefab and enter Play Mode to test spawning, collision, enemies, items, camera scrolling, level completion, and multiplayer synchronization.

The solidRect, block, and enemy arrays on WorldController contain generated bake results and should not normally be edited by hand. Re-run the map bake whenever a Tilemap or spawn marker changes.

Multiplayer Synchronization

The game uses an owner-driven synchronization model. The current owner runs the primary game logic and synchronizes menu state, level progress, score, lives, items, enemy state, and key gameplay events.

Player movement uses a separate snapshot stream with remote interpolation. When a player joins late or ownership changes, progress snapshots are used to realign the main game state.

Known Limitations

• Multiplayer synchronization is not intended to be perfectly frame-accurate. Small position or animation timing differences may occur between clients.
• Two-player mode alternates between Mario and Luigi; it does not allow both characters to be controlled at the same time.
• During ownership transfers or periods of high network latency, a transition mask may briefly appear while the game state is realigned.
• The project is primarily developed against the Unity and VRChat SDK versions listed above. Compatibility with other versions is not guaranteed.

Folder Structure

• Animations: Animation assets.
• DLC: Optional content such as Bill Mode.
• Editor: Level baking and Unity Editor tools.
• Materials, Models, Shaders: Models and rendering assets.
• NES: Retro TV and console-related assets.
• Prefabs: Core game objects, scene components, and entity Prefabs.
• Scenes: Sample scene.
• Sounds, Textures, Tiles: Audio, texture, and level Tile assets.
• UScripts: Main UdonSharp gameplay code.

Credits and License

Original code written for this project is licensed under the MIT License. See LICENSE.txt for details.

Third-party models, textures, audio, and Nintendo-related assets are not covered by the MIT License. Their respective copyrights and licenses remain with their original creators and rights holders. This is an unofficial fan-made project and is not affiliated with, endorsed by, or sponsored by Nintendo.

中文

项目简介

SuperMarioVRC 是一个使用 Unity、VRChat SDK Worlds 和 UdonSharp 制作的非官方同人项目，尝试在 VRChat 中还原 FC / NES 版《Super Mario Bros.》的关卡、操作和游戏流程。

项目同时支持桌面端与 VR 操作，并为多人实例实现了游戏状态、玩家动作和关键事件同步。

主要功能

• 收录 World 1-1 至 World 8-4，以及地下、水下、天空和隐藏区域。
• 支持单人模式和 Mario / Luigi 轮流进行的双人模式。
• 包含移动、跳跃、游泳、水管、藤蔓、检查点、城堡迷宫和关卡结算流程。
• 包含金币、蘑菇、火焰花、无敌星、火球、常见敌人和 Boss。
• 支持桌面键盘与 VRChat 输入事件。
• 支持多人状态同步、新玩家加入和游戏 owner 切换。
• 提供基础游戏 Prefab、复古电视版本和可选 Bill Mode。

环境要求

依赖	版本
Unity	2022.3.22f1
VRChat SDK Worlds	3.10.4
UdonSharp	随 VRChat SDK Worlds 提供

建议使用 ALCOM 创建或管理 Worlds 项目。

导入方式

1. 使用 ALCOM 或者 VRChat Creator Companion 创建一个 Worlds 项目。
2. 确认 Unity 与 VRChat SDK Worlds 版本符合上表要求。
3. 下载并导入发布页面提供的 SuperMarioVRC.unitypackage 资产包。
4. 等待 Unity 完成资源导入和 UdonSharp 编译。
5. 打开 Assets/SuperMario/Scenes/SuperMario.unity 查看示例场景，或将需要的 Prefab 放入自己的场景。

导入完成后，可以安装 TextMeshPro（TMP）以正常显示测试面板和使用说明。如果项目尚未配置 TMP，请先通过 Package Manager 安装 TextMeshPro，再选择 Window > TextMeshPro > Import TMP Essential Resources 导入基础资源。

操作方式

开始游戏前需要先拾取游戏控制器。

操作	桌面端	VR
移动 / 菜单选择	方向键	左摇杆
跳跃 / 确认	J	A
奔跑 / 发射火球	K	RT

桌面端按键可以在 InputController 组件中修改。

主要 Prefab

• Prefabs/SuperMario.prefab：不包含外部电视模型的核心游戏对象。
• Prefabs/Retro TV Mario.prefab：包含复古电视显示效果的完整版本。
• Prefabs/Instruction Mario.prefab：操作说明面板。
• Prefabs/GameTestPanel.prefab：开发和调试用测试面板。

SuperMario.prefab 内的主要对象：

对象	作用
ScreenRoot、Screen、UI Manager	显示游戏画面、HUD、标题菜单和流程提示。
Controller	提供可拾取的游戏控制器，读取桌面端和 VR 输入，并申请游戏控制权。
GameManager、LevelController	管理游戏模式、得分与生命、关卡切换、计时、镜头和结算流程。
Player	处理角色移动、碰撞、动画、受伤和强化状态。
EntityManager、ObjectPoolManager、ScoreManager	管理敌人、道具、投射物、对象池和分数提示。
SyncController、PlayerMotionSync、SyncPayloadCodec	同步游戏状态、关键事件和玩家移动。
AudioManager、PaletteManager、TitleDemoController	管理音效、画面配色和标题演示。
BillDLC、GameTestPanel、GameRestartCanvas	提供可选模式、开发测试和游戏重启功能。

制作新地图

1. 在 SuperMario.prefab 中找到现有关卡，复制一个类型接近的 World X-Y 作为模板，例如地面、地下、水下或城堡关卡。
2. 重命名关卡根对象及其 Tilemap。也可以使用 SuperMario > Tools > World X-Y Name Replace 批量修改对象名称和 HUD 世界编号。
3. 在 WorldController 中设置关卡编号、配色、计时、地图宽度、镜头、出生点和 nextWorld 等基本参数。
4. 编辑关卡中的主要 Tilemap：普通 Tilemap 负责画面，TerrainCollider 负责地形碰撞，InteractiveBlock 放置砖块、道具和终点标记，Enemies 放置敌人及平台生成标记。
5. 根据需要配置水管入口与出口、检查点、藤蔓、终点行走目标和其他特殊关卡机制。
6. 选中关卡的 WorldController，点击 Bake All Child Map Data，将碰撞、交互块和敌人标记烘焙为运行时数据。也可以通过 SuperMario > Level Bake Tool 分别进行烘焙。
7. 将新关卡按正确顺序加入 LevelController.worlds，并检查前后关卡的 nextWorld、水管目标和其他跳转引用。
8. 保存 Prefab 后进入 Play Mode，测试出生点、碰撞、敌人、道具、镜头滚动、关卡结算和多人同步。

WorldController 中的 solidRect、block 和 enemy 数组属于烘焙结果，不建议手动修改。Tilemap 或生成标记发生变化后，应重新执行地图烘焙。

多人同步

游戏采用 owner 驱动的同步方式。当前 owner 负责处理主要游戏逻辑，并同步菜单、关卡进度、得分、生命、道具、敌人状态和关键流程事件。

玩家移动使用独立快照进行远端插值。新玩家加入或 owner 发生变化时，游戏会通过进度快照重新对齐主要状态。

已知限制

• 多人同步不追求逐帧完全一致，不同客户端之间可能存在轻微的位置或动画时间差。
• 双人模式为 Mario 与 Luigi 轮流游玩，不是两个角色同时操作。
• owner 切换和网络延迟较高时，短时间内可能出现画面遮罩或状态重新对齐。
• 项目主要按照上方列出的 Unity 和 VRChat SDK 版本开发，其他版本未保证兼容。

目录结构

• Animations：动画资源。
• DLC：Bill Mode 等可选内容。
• Editor：关卡烘焙和编辑器工具。
• Materials、Models、Shaders：模型与渲染资源。
• NES：复古电视和主机相关资源。
• Prefabs：游戏主体、场景组件和实体 Prefab。
• Scenes：示例场景。
• Sounds、Textures、Tiles：音频、贴图和关卡 Tile 资源。
• UScripts：主要 UdonSharp 游戏代码。

致谢与授权

本项目的原创代码使用 MIT License，详见 LICENSE.txt。

第三方模型、纹理、音频以及 Nintendo 相关素材不包含在 MIT 授权范围内，其版权和许可归各自作者及权利人所有。本项目为非官方同人项目，与 Nintendo 无关联，也未获得其认可或赞助。