# PolkaCombat: Mugen Server Documentation plus(+) Local Development of the Customized Mugen

If you are only looking for the section where you want to know how to setup or develop locally the Customized Mugen repository. Please jump to the end of this document - last section.

<hr>

<br>

This custom mugen was built using two separate languages. There is the mugen itself which is using C#. Then the customization was implemented by using ES6+ (Node, React). Given the nature of mugen, C# is not easy, that's why using the other language was the viable choice. Project nickname is "Ultimate AI Mode".

It is very important to read this whole documentation first. Overall, the most important section here is the "**Vital Steps Before Running the App**". Be sure to read that section thoroughly.

<br>

:::info
:bulb: Recommended to read the whole documentaion.
:::

<br>

### :pushpin: Vital Files and Directories

1. **App-Assets directory**
The '*app-assets*' directory is vital because it contains all files that are necessary or that supports the aesthetic aspect of the app. Wihtout this directory, the app will not run. The files inside this directory are the app, background, and sponsors.

1.1 **'app' directory**
This is where your brand logo is located

1.2 **'background' directory**
This is where your main background image is located

1.3 **'sponsors' directory**
Although, this is optional, it is recommended to have this included to add great aesthetic to pre and post match screens. Just check the settings section on how to turn this on/off. As the name suggest, this section is great if you have sponsors or you want to promote other supporters.

2. **UAIM.exe File**
This is the application file for this custom mugen app.

3. **MugenWatcher.exe File**
This application file is the one possible for getting the results after each match.

4. **mugen.exe File and All part of it**
This is the main default Mugen application file.

5. **uaim-conf.json File**
This is the configuration file for this custom mugen app (UAIM.exe). Please check below for in-depth details.

<br>
<br>
<br>

### :pushpin: The Flow or Sequence of each screens
Since this custom mugen is using two languages, different codebase - we need to make sure that the flow is seamless or for it to look as if the app was built natively with one codebase. Since this will be streamed, it is important to familiarize the sequence of the screens. Because there might be a situation where the screen is not showing up - because of window-focus issues. But it's least it will happen and there is a solution for that. Just follow the instructions written in the following sections below this section. When you run the app (**UAIM.exe**) file, this is how the flow would look:

- **The 'Loading Screen'**
This will only fire once. The moment you click the UAIM.exe file this will just run once.

- **The 'Waiting Screen'**
This section will select randomly the characters and stage. This will run about 30 seconds, depending on what you set in the configuration file. This is also the section where the users/bettors will place their bets.

- **The 'Pre-Match Screen'**
This section shows before the main Match Screen for about 7 seconds. This is important because this is where we send the match details to the server api, letting the server know that a match is about to start.

- **The 'Match Screen'**
This is the main screen of any Mugen match.

- **The 'Post-Match Screen'**
This is the last screen of the flow, this is vital because this is where we also let the server know that the match has ended, sending details who won and which character lost the match. After a couple of seconds it will loop back to '**Waiting Screen**'.

<br>
<br>
<br>

### :pushpin: The Configuration File (uaim-conf.json)

This is the configuration of this custom mugen application. If you can see this '**NOT ADVISABLE TO CHANGE**' in the description column, please do not change it.

### Properties
----------

| Name | Description |
| ---- | ----------- |
`waitingScreenCountdownMsg` | Message to show while on 'Waiting Screen' |
`waitingScreenDuration` | Length of seconds before closing 'Waiting Screen' (default: 30000 milleseconds which equals to 30 seconds) |
`delayBeforeMinimize` | Length of seconds before minimizing 'Pre-Match Screen' (default: 7000 milleseconds which equals to 7 seconds) |
`showSponsors` | Either show or hide the Sponsors section (default: true, it can improve design aesthetics) |
`sponsors` | The images' names of the sponsors. These images are placed inside *app-assets* directory. |
`logo` | Your logo or brand, put image name here, still inside the *app-assets* directory. |
`prepostBackground` | The Pre and Post screens' background, still inside the *app-assets* directory. |
`roundCount` | Number of match rounds in order to win (default: 2) |
| `categories` | List of categories (see below) |
| `stages` | List of stages (see below) |
| `characterAnimationOptions.x` | X coordinate for the character animation (default: `47vw`) |
| `characterAnimationOptions.y` | Y coordinate (from bottom) for the character animation (default: `2vh`) |
| `characterAnimationOptions.scaleFactor` | Scale factor for the character animation (default: `1`) |
| `characterNameOptions.x` | Character name x coordinate (default: `40vw`) |
| `width` | Not Advisable to change |
| `height` | Not Advisable to change |
| `fullscreen` | Not Advisable to change (default: `false`) |
| `frame` | Not Advisable to change (default: `true`) |
| `background` | Not Advisable to change |
| `sound` | Not Advisable to change |
| `motif` | Not Advisable to change |

### Category properties
-------------------

| Name | Description |
| ---- | ----------- |
| `characters` | List of characters (see below) |
| `random` | Indicates that the category is a random selection (default: `false`) |

### Character properties
--------------------

| Name | Description |
| ---- | ----------- |
| `definition` | Definition file path |
| `styleName` | Style name (default: `Style 1`) |
| `portrait` | Image path of the character portrait (default: `portrait.png`) |
| `portraitOptions.x` | Portrait x coordinate (default: `50vw`) |
| `stand` | Image path of the character stand animation (default: `stand.gif`) |
| `stand2` | Image path of the character stand animation for color 2 (default: `stand2.gif`) |
| `standOptions.x` | Override x coordinate for the character stand animation (default: `47vw`) |
| `standOptions.y` | Override y coordinate for the character stand animation (default: `2vh`) |
| `standOptions.scale` | Set the scale factor of the character stand animation (default: `1`) |
| `thumbnail` | Image path of the character thumbnail (default: `thumbnail.png`) |
| `styles` | Alternative styles. List of characters (default: `[]`) |
| `random` | Indicates that this character is random one within category (default: `false`) |

### Stage properties
----------------

| Name | Description |
| ---- | ----------- |
| `definition` | Definition file path |
| `random` | Indicates a random stage (default: `false`) |

<br>

:::info
:bulb: Do not worry too much about this section. There is already a sample uaim-conf.json file included. And, there will be a section below on how to add characters and stages.
:::

<br>
<br>
<br>

----------------
### :pushpin: :exclamation: Vital Steps Before Running the App :exclamation:

This section is considered to be the most important part because this is where you will follow most of the tasks required in order for the app to fully function. Since this a combination of two technologies/languages, it is important that you are aware of window-focus issues and audio issues. Especially since this will be running on a Windows OS machine.

1. **First, open the folder of the app where all the files are located**
Since this is deployed in a VM windows server, just go to the Downloads section and find "*Final PolkaCombat App*" folder

1. **Pin the UAIM.exe and MugenWatcher.exe to Taskbar**
It is recommended to pin these two files in the Taskbar so that both can be easily accessed.

3. **Change Desktop Background**
It is important that you must change the desktop's background. The background image file is placed inside the '*app-assets/background*' directory. Use that as a background. You can change the image file as long as you will use a very High Definition image. And, be sure to change the `prepostBackground` property in the *uaim-conf.json* file as well. Just put the file name of the background image you are planning to use. Why this is important? Because what you set here is also going to be used as the background image of the Pre and Post Screens. As a result, there would be no obvious transition delay if the screens or windows are interchanging.

5. **Close or Minimize Other Apps**
It is recommended to close or minimize all apps except your streaming software like OBS, but later, after you're done setting up with your streaming software you still need to minimize it. This will help avoid any window-focus issues.

7. **Mugen Watcher**
This is the first step in order to run this custom app. **Run** the **MugenWatcher.exe** file first. This is one of vital files listed above since this application enables to get the match results. **After** you ran the file, **minimize it**, and you can just leave the MugenWatcher minimized all throughout.

5. **Run the UAIM.exe**
Then, after step 4, just run the UAIM.exe file, the one you pinned in the Taskbar.

7. **Screen Flow, Window-Focus, and Audio**
This part is the most crucial one. As stated above, it is important to familiarize the Screen Flow. So that you would already know what screen is going to show next.

The common issues here are window-focus and audio. Both are related. The window-focus issue in Windows OS platform is when an application is running but is not yet in focus. It means, it is running but the audio is not audible yet because the application's window is not yet focused or the user did not click it again.

So in order to hear the sound of UAIM.exe and mugen.exe files, each should be focused depending on which one should be audible on a specific instance.

For example, upon clicking the UAIM.exe file in step 5, it should play the background sound of the UAIM.exe. **IF IT IS NOT PLAYING** - you need to click the window or frame of the UAIM.exe to enable the sound.

This would be the **necessary steps** so that both UAIM.exe and mugen.exe will play all throughout the loop without clicking each of the app all over again.

:fire: :eyes: ------- **Eyes Here** ------- :eyes: :fire:

**6.1** After clicking the UAIM.exe in step 5, the "Loading Screen" will show up and then the "Waiting Screen" will show next. You can click the UAIM.exe frame or window now, so that it will be focused and will enable the sound.

**6.2** Then, click somewhere on your desktop, anywhere on your desktop

**6.3** By this time, the "Pre-Match Screen" or "Match Screen" will show up. If the "Match Screen" will show, it means you are now seeing the Mugen's frame/window. First run, it will not play any background sounds. So, again, you need to click the "Match Screen" or the Mugen's frame/window to focus or enable the sounds.

:fire: :eyes: ------------------------- :eyes: :fire:

That would be your last step in order for these two applications, the UAIM.exe and mugen.exe applications to continuously play sounds all throughout the stream. Basically, the last click would be on the "Match Screen" or the Mugen's frame/window. **Do not click** on other apps anymore if you want to play their sounds throughout the loop. That's why it is so important to set up the audio level first of your system, to prepare the streaming software as well.
<br>

#### :exclamation: **PLEASE TAKE NOTE OF THESE, *BEFORE PROCEEDING TO STEP* 8**
----------

:exclamation: **NOTE 1**: **Sometimes**, the screen will not show anything (plain black), OR the next expected screen is not showing up, **the solution** is to only click the frame or window again. And if the audio is not playing again, :wave: ***just repeat 6.1 to 6.3 steps***.

:exclamation: **NOTE 2**: During the first run, or second or third run, The "Match Screen" or the Mugen frame/window will be **loading really slow**. That's normal. After second or third run, it will be smooth already. And by run, it simply means each loop - from "Waiting Screen" up to "Post-Match Screen" (see *The Flow of the Main App* section above to familiarize screens).

:exclamation: **NOTE 3**: **Do not maximize** the "Match Screen" or Mugen window. Avoid fullscreen so that the resolution will visually great for streaming.

9. **Run Streaming Software (OBS, etc)**
Last step is the streaming part. Do not stream it yet, just prepare it first. Run the app first many times until you are confident that the app is smooth and is playing sounds each loop. **The important note in this step** is that you should only stream the inner frame/window. Do not include the 'Control Bar' where the **-- [] X** buttons can be seen.

Both UAIM.exe and mugen.exe applications are aligned and of the same height and width. That's why it is not recommended to change these properties.

:exclamation: The end-goal here is to look like what it is shown in the images below: <br><br> If on the 'Waiting Screen', the red circle in the image must be highlighted. It means that the app is being focused (selected). This is important so that the audio will play.
 <br><br> Same goes with the official mugen window. It must be highlighted so that audio will play. Again, if on the mugen window and the icon below (encircled red) is not highlighted it means that it is not focused. You need to click the window frame of the mugen app in order to focus it.
 <br><br> **After it is already focused, just leave it. From there it will auto select itself. Your last click must be the window frame of mugen app. Do not click anywhere. Just disconnect from the NoMachine connection.**

<br>

:::info
:bulb: **Note** Recommended is to use a PC or Laptop solely for streaming this custom mugen app. So that the window-focus and audio issues will not occur. It means if you're planning to stream this custom application to a PC or Laptop that will be also used for other tasks, like browsing or editing photos, watching videos, etc., then that would not be ideal.
:::

<br>
<br>
<br>

### :pushpin: Connecting to the mugen windows server
1. Download the free software called NoMachine https://www.nomachine.com/ then install it on your machine.

3. Open NoMachine then Add New Connection then just type what you see here in the image below
you can just change the name to PolkaCombatServer, or any name you like.

4. Then highlight the newly created connection, then click Connect

6. Initial load will show you some options, make sure you follow these settings below:
check the green circle
mute the audio
just follow this setting
don't resize the remote display

8. After it connects, it will now show you the windows server where our custom mugen game is running. If in case it will ask for the windows account login, just enter this:

*username*: MelodicCrypter
*password*: Bw:RWCSS?XfD0Jjev48R

6. Check your NoMachine setting again and make sure that audio and mic are turned off. To go the main settings when you are already inside the windows machine, just follow this:

either pressing the combination key or just point your mouse to the top-right corner
then just set it

8. If you want to disconnect from the current connection, go to settings again then click the Connection button then click 'disconnect'

10. That's all you need to do if you want to connect/disconnect to our mugen server

<br>
<br>
<br>

### :pushpin: What to do if the mugen crashes
1. First, connect to the mugen server using the instructions in the section [above](#-Connecting-to-the-mugen-windows-server)

3. If the mugen app is not responding, just click the close button. Just click one time, this is important. Just click one time. Allow it to close itself. After that it will automatically open the UAIM.exe app to load the next match. Also, do not stop the streaming, just continue streaming.

5. After that, do not click anywhere. This is vital because of the focus issue. This is discussed in detail above. So after closing mugen window, do not click anywhere, just directly go to the NoMachine settings then click disconnect.

<br>
<br>
<br>

### :pushpin: Adding New Character

Add your character in the `chars` directory like usual.

### Register the character
----------------------

Edit the file `uaim-conf.json` and add theses lines in `"catagories"` property:

    {
      "name": "Street Fighter",
      "characters": [
        {
          "definition": "ryu/ryu.def"
        }
      ]
    }

Now the file looks like:

{
  "logo": "tempLogo.png",
  "prepostBackground": "UltimateAIMode-WHDBg.jpg",
  "roundCount": 2,
  "categories": [
    {
      "name": "Street Fighter",
      "characters": [
        {
          "definition": "ryu/ryu.def"
        }
      ]
    }
  ],
  "stages": [],
  ...
}

### Add the character portrait
--------------------------

Add a file `portrait.png` inside the character directory. You can use this template to keep the same face size for all your characters:


You can also customize the image path:

{
  "definition": "ryu/ryu.def",
  "portrait": "path/to/portrait.png"
}

<br>
<br>
<br>

### :pushpin: Adding Stand Animations
There are two ways to add a stand animation for a character.

#### A. Add the character stand animation (single color only)
---------------------------------

Download and open the definition file with [Fighter Factory Studio](http://fighterfactory.virtualltek.com/)

Go to the `Animation` view and export the stand animation in the character directory as `stand.gif`. That's it. But if you will save it inside another directory, here's how you would do it:

{
  "definition": "ryu/ryu.def",
  "stand": "path/to/stand.gif"
}

#### B. Add the character stand animation (multiple character colors)
---------------------------------

In order to create stand animation for each character color is still by using the export tool of [Fighter Factory Studio](http://fighterfactory.virtualltek.com/).

1. Open the character definition file in Fighter Factory Studio
2. Click on the `Tools` menu
3. Click on the `Export to HTML` menu
4. Confirm with `OK`
5. Save witht he name `export`

Now you have `export.html` file in the character directory and stand animations in `images` directory.

:::info
:bulb: **Note** Just follow the conventional naming for each method and it will be automatically detected by the UAIM.exe app.
:::

<br>
<br>
<br>

### :pushpin: How To Change Match Time
In order to change a battle/match time, navigate to and click 'data/mugen.cfg' file then look for this line:

time = 70

then change it to whatever time you want to set.

<br>
<br>
<br>

### :pushpin: How To Add New Lifebars
In order to add new lifebars:

1. Navigate to *'fight'* directory
2. Create a new directory, e.g '*fight-07'*
3. Then inside that new directory, paste or extract the files
4. If the extracted files contains a *'font'* directory, move all the fonts/files inside that directory (*fights/fight-07/font/*) into the *'font'* directory in the root section (font/)

<br>
<br>
<br>

:::info
:bulb: BELOW IS A SIMPLE GUIDE IN ORDER TO GET STARTED WHEN DEVELOPING THE CUSTOMIZED MUGEN LOCALLY.
:::

<br>
<br>

### :pushpin: When Developing Locally (Editing the Customized Mugen Repo)
The codebase is built on top of Electron with React. But before you can start properly you must download this directory first:

**this link will expire in 7 days from the latest time this doc was published:**
https://we.tl/t-fcg6FUWB2K

Guide:

1. First, clone the repo for the customized Mugen game here: https://github.com/MelodicCrypter/CustomNegumCodebase
2. After you cloned it and already placed it on your local directory. Make sure that you also already have downloaded the link above. And, check if it is named 'dev-mugen-from-download'. If it is, copy all its contents (*only the contents, do not copy the directory itself*) and paste it in the clonedRepoLocation/dev-mugen/pasteAllDownloadedContentsHere
3. After you clone the repo, you can also see that there is a single text file named 'READ THIS FIRST. You can just delete that after you paste all the contents from directory you just downloaded.
4. From there, you can study the repo codebase starting from: ***package.json, index.jsx, getCurrentDirectory.js, and app.jsx***.
5. If you want to run it just run 'npm start'.

<br>
<br>
<br>