WIGUx mod for EmuVR - umbrella-mod-team/Umbrella-Samples GitHub Wiki

WIGUx mod for EmuVR"

EMUVR is a closed platform that seeks to recreate a virtual reality (VR) experience for emulators of classic gaming systems. It allows users to immerse themselves in virtual environments that mimic the look and feel of old video game systems.

Until recently we had a limited number of systems and objects to use in the world, until the mod appearedWIGUallowing the use of filesUGC (User Game Content) within the emulator in the form of decoration or new systems.

All this has opened the door to a community eager to contribute and contribute to this world of emulation.

1 - [What this mod does]

WIGUx It is a modification ofWIGU v0.12.6 which basically enhances its features and includes new functionalities in addition to providing tools to extend it.

  • Expand the modification options of the current room through the

    configuration file

    • Removal of furniture, door, switch

    • Elimination of external environment (houses, trees, etc...)

  • Possibility of loadingnew levels (via UGC)

  • possibility ofcreate portals type door or switch that loads

    another room

  • New bindings for player movement

    • "P" key Prints the position of the character on the screen

    • Right/left/up/down cursor keys rotate the character's camera

    • Run mode:Press SHIFT+cursor or Left Trigger+JoyPad direction

    • In VR Two joystick triggers pressed + right joystick up/down

      regulates the height of the character

  • Extend UGC functionality through C# libraries

  • Books

  • Tools included

    • Content Manager

      • UGC explorer

      • Room Manager

      • Modules (Scripts) Manager

    • FindDupplicatedUgcs: Find duplicate UGC's in your folder

    • LiVRo2WIGUx: Convert books from LiVRo format to WIGUx

    • Book2WIGUx: Convert PDF books to WIGUx

2 - [Clean Installation]

Instructions for use:

- Download and unzip the official version ofEmuVR 1.0.12 [official]{.underline}

- Download the[last version]{.underline} ofWIGUx from the pinned official channel in the same folderEmuVR.**
** Important!!! This option will overwrite rooms 1,2,3,4 make sure you don't have any in those numbers!

3 - [ Content Manager ]

In order to manage EmuVR and some of the WIGUx features, a tool has been included to do so in an easy and intuitive way.

To start it open EmuVR\WIGUx\Content Manager\WIGUx.Manager.exe

3.1 Toolbar

Allows quick access to contextual options

{width="1.46875in" height="0.34375in"}

  • Running EmuVR Desktop.

  • For current running of EmuVR.

  • Refresh current list.

  • Open preferences screen.

3.2 UGC Explorer

Allows exploration and maintenance ofUGCs located in EmuVR\Custom\UGC and includes a real-time model viewer.

From thetree content components can be dragged to move them between folders.

Selecting each element will update the element displayed in the viewer.

The viewer allows you to interact with the object through the keyboard.

SHIFT+Cursors Right/Left Rotates the camera over the object

SHIFT+Up/Down arrow keys: Zoom in/out of the camera

ALT+Cursors: Move thecamera directionally on the 3d model

{width="5.014615048118985in" height="3.5989588801399823in"}

Other options are to drag and drop elements to manage your UGC library, with the right button we will have a contextual menu with various options:

{width="4.697916666666667in" height="3.40625in"}

3.4 Room Manager

The room manager allows you to view the current structure of your rooms in tree form.

When selecting each room we will obtain a tab with the current configuration where we can activate or deactivate its features so that we can have a personalized experience in each one.

"Fan": Show/Hide the fan.

"Door Switch": Show/Hide the switch next to the main door.
"Door": View/Hide the main door, ideal for putting a customized one.

"Use Custom Image": Allows you to customize the default photo for this room.

"Passthrough": Disable the environment to use viewer passthrough through Virtual Desktop. (Controls position the environment)

"Room UGC": Shows a list of all available rooms inEmuVR\WIGUx\Rooms in UGC format. Here is a guide to make yours personalized.

{width="6.213542213473316in" height="5.416933508311461in"}

3.5 Preferences

In the preferences dialog we have different WIGUx configurations.{width="5.026042213473316in" height="4.669865485564304in"}

Debug: Enables a verbose mode in the console window showing debug messages so that in the event of an incident, we can understand the problem and send it to the developers

Extra Keyboard- Enables additional movement keys with the keyboard, the cursors do camera rotation to simulate the character turning.

Default Book: Select the UGC of the book model to use by default found inEmuVR\WIGUx\Books

Modules:

The modules are .net assemblies that are added to the modules folder and allow us to add extra functionality to our UGC's, once copied to the folder. We reopen Content Manager to read these new assemblies. We open the configuration screen again and drag the UGC file from the explorer with the mouse to the list to add it, we select it and press the "Add Module to UGC" button and select the MonoBehaviour that we want to associate with our UGC.

3 - [Modifying the Original Room]

3.1 Basic concepts

Currently EmuVR has configuration files for all the rooms that we save in the game.

These files are located in the folderEmuVR\Saved Data\Rooms where for each room there are 2 files
{width="5.6875in" height="4.625in"}

Slot5.json : Includes room configuration metadata, objects, systems, games...

Slot5.png : Image of your room when saving

Having that clear, it is very easy to create an identical room, for example if we want to create aroom number 6 based on the one cited in the previous example (room number 5), we will only have to copy these two files and rename them toSlot6.json y Slot6.png.

3.2 Room configuration structure

Before starting to edit files, the first thing is to understand how they work, inEmuVR\Saved Data\Rooms open the Slot6.json file with an editor (We recommend Visual Studio Code[Download Visual Studio Code - Mac, Linux, Windows]{.underline}) and you will see something like this:

This file is like an object store with metadata/configuration for everything that this room includes.

InWIGUx In addition to the basic properties, we have extended these files with new configurations to be able to take the default room to a second level:

"fan": enable/disable the fan. The values ​​can betrue/false.
"switch": Enables/disables the switch. The values ​​can betrue/false.
"door": Enable/disable the main door. The values ​​can betrue/false.

"furniture": removes all the default furniture from the room, ideal for making your own compositions. The values ​​can betrue/false.

"backyard"- Loads the exterior scene of all houses and trees, and exterior lighting based on time. In the future we will include APIs for better control. The values ​​can betrue/false.

{width="4.453125546806649in" height="2.362154418197725in"}

Within the baseline are included the [original room furniture]{.underline} so you can learn and create your own compositions

4 - [ Creating your Personalized Room ]

Sometimes the default room may fall short for some scenarios, the mod allows you to eliminate it and be able to use anyUGC like your main room. If you want one to load room 7 or 8 or you can even create it from 0!!

4.1 Creating your UGC room in Unity

The instructions for creating a room are practically identical to creating a simple UGC object, with a few variations.

If you have questions about how to create a UGC, here you go[a great tutorial]{.underline} in Spanish

Open Unity 2018.4.12f and create a new project with the 3d template and from the menu Assets > Import Package > Custom Package... Select the UGC toolkit Package (it has

It is time to import the map that we had created, open an explorer, select your .pbx or generated file and drag it to the Assets window

{width="6.020833333333333in" height="3.0110837707786526in"}

Once displayed on the screen, make sure that the Transform property is x:0 y:0 z:0 and make sure you have the correct scale, taking as reference the examples in UGC prefab.

If the map includes assets, try to empty everything that can be independent in UGC, this will lower the number of polygons and also re-position objects

4.2 Adding walls and floor with collision

On maps, collisions are treated in a special way, first we will create[BoxCollider for the floor, walls and walls]{.underline}. Make sure you do this in a smart way, add this collider[makes the room interact with the physics of the objects]{.underline}.

However, [this is not enough for interaction with the player]{.underline}, for this we must select the GameObject that contains the BoxCollider component and [In the Layer selector we select Walls]{.underline} (Layer 9)

{width="6.302083333333333in" height="1.6779538495188102in"}

If it does not exist, we add it from Tags & Layers in User Layer 9: Walls as shown in the image.

{width="5.077609361329833in" height="2.257963692038495in"}

Now we should have collision when moving and with the collision of objects. It's time to export to UGC and try out our new room.

Tip: If you need to test a level with two heights you can use the ["Q" and "E" keys]{.underline} for the in [modo VR]{.underline} squeezing the[two triggers and up/down with the right stick]{.underline} for[up down]{.underline} the player.

In the Hierarchy window select your main layer and add a UGC Info component, include Name, Author, Version. Check that the Polycount number is not too high to avoid performance problems, fix errors if any and press Export UGC.

This should generate the file we need in**EmuVR\Custom\UGC
**

{width="3.403380358705162in" height="3.6093755468066493in"}

Advice for scale: Sometimes imported models don't have correct sizes, and it's hard to tell that they're actually too big or too small until you export them and see them in-game. To measure your objects accurately, you can drag the "Measuring Tape" and "Coke For Scale" prefabs from the "Assets/UGC Kit/Helper Prefabs/Misc" folder into your scene. Remember to remove them from your UGC before exporting it.

Here are some pre-assembled examples of UGC prefabs of different types that you can import into your Unity project to learn how they are configured. It is also an example of how to distribute and organize your files and folders. They are ready to be exported as UGC files:

  • Stool (Taburete)

  • LCD TV (LCD TV)

  • Sega Master System

  • Sega Master System Cartridge (Only rough unpolished examples for

    now)

Download:[UGC_Examples.unitypackage]{.underline}

Here are some useful tutorials on how to download and import models, or import them from Blender (check out the two videos there!):

[https://marketsplash.com/tutorials/unity-3d/how-to-import-3d-models-into-unity/]{.underline}

Here's a pretty good and short tutorial showing how to add multiple simple colliders to fit the shape of your object:

[https://www.youtube.com/watch?v=P5F91E_p_zk]{.underline}

This shows how to rotate secondary colliders:

[https://www.youtube.com/watch?v=lr09elWiRqo]{.underline}

Important:

Tip: There are many free templates to download

[https://sketchfab.com/features/free-3d-models]{.underline}

Be careful with the polygon counter! Think about bad graphics cards in VR...

Look for "game ready", "PBR" and "lowpoly" for (hopefully) attractive optimized models.

However, if you get some paid model, don't share the original files here, just like the ROMs! However, sharing the exported .ucg file is fine.

4.3 Adding your Custom Room

Once the .ugc is generated we will make sure that it is copied to the folderEmuVR\Custom\UGC

Now we go to the rooms folderEmuVR\Saved Data\Rooms and we open the configuration file of the room we want, e.g. Slot8.json

First we disable the room objects from the Content Manager or by modifying the room configuration file:

"fan": false,

"door": false,

"door_switch": false

"backyard": false

Now we add a new rooms node, which is a collection of all the rooms in UGC that we want to load in this room (as a general rule we will only load one)

"rooms": [
{

"id": UGC identifier of the room that we want to load

"position": position of the room in the world

"rotation": room rotation
"scale": room size

}

]

{width="4.4375in" height="3.338542213473316in"}

Once added, save the file and startEmuVR, open the settings screen and load the map number! You should now be able to enjoy your new custom map!

{width="6.5in" height="3.5555555555555554in"}

Tips:

  1. If the scale size is not correct be sure to follow[[this

    tab]{.underline}](#dw3z5l6cup47)

  2. If the room is rotated, you probably haven't converted the

    coordinates to Unity correctly, be sure to follow the guide

5 - [Your first portal]

The portal system allows you to travel to different saved rooms through objects placed on the stage.

These portals are saved in the room settings and include information about their position in the environment and the room where they will take the user when the mechanism is activated.

Currently there are:

  • Collision Type: The user will be transported when they collide

    with the object (e.g. a door type)

  • **Switch Type:**The user will be transported when they select the

    switch type portal and press space key or press the right stick

An example of how to add a portal in the configuration:

{width="2.527415791776028in" height="3.8196281714785654in"}

Defining properties in a portal configuration:

"id" : defines the ugc identifier that you want to load for the portal

"position": defines the position of the portal within the environment

"rotation": defines the rotation of the portal within the environment

"scale": defines the size of the portal within the environment

"target": data related to the room to which we want to transport ourselves

"room_id": room number to which we want to travel
"position": position of the character when he appears in the new room
"rotation": direction where the character will be facing when they appear in the new room

You can make round-trip or multiple portals in the same room! The possibilities are endless!

Tip 1: Currently the portals can be moved in the game but the new position is not saved with the room. To position ourselves, search in the UGC menu for the model you use for the portal, drop it, drag it and fix it in the position you want, save the room and open the room in the Code Editor and search for the UGC in objects, copy its properties positioning, rotation and size to the portal.

Tip 2: If you press the "P" key, the character's position is printed on the console, which can help you orient yourself with the positions.

In the future this can be done from the content manager

6 - [ Extending with your own Scripts ]Advanced

This section requires knowledge of programming and Unity!!
When we are creatingObjects or new systems, EmuVR allows us through UGC to give more realism to our creations through an animation system, but this is sometimes insufficient if we need to perform more complex actions.

UGC, being resource files, cannot contain Scripts that are not in the main assembly, which is why at WIGUx we have incorporated different extensibility points, which allow you to more easily extend the EmuVR code.

To simplify the process we have created an example solutionwith a solution with two usage examples. To open it you need[Visual Studio 2023]{.underline} (or any code editor) and have knowledge of C#.

The projects are located inEmuVR\WIGUx\Source and contains the following:

MonkeyIslandWheelModule:

More elaborate example that adds a Component of type MonoBehaviour to a UGC in the startup phase of EmuVR.{width="2.2343755468066493in" height="1.9270833333333333in"}

This example requires the UGC of the Monkey Island TM roulette, which contains two layers, the upper and the lower one, which is included in the official pack.

The script makes sure that the spinner is held in the hand and the top rotates by pressing the left/right triggers or the "J" or "H" keys.

{width="2.5625in" height="1.924187445319335in"}

AnimatedPlaneModule:

Another example containing a Component of type MonoBehaviourwhich on the one hand changes the rotation animation that is in the propeller in Start, to a loop mode at the beginning of the script. In the update we check if the plane collides with a box collider and changes direction.

6.1 Extension Points

ALL

6.2 Creating my first Script

ALL

6.3 Testing my first Script

7 - [ FAQ ]

Help, I have a problem with the build:

Modifying EMUVR at such a level is a complex task, which can break EmuVR in many ways and sometimes finding the solution can be a complicated task without having information.

Instead of sending screenshots of the Output window, we will need the log file located inEmuVR\MelonLoader\Lastest.log