search

Flazhik / CybergrindMusicExplorer

An ULTRAKILL mod that allows you to add custom songs to Cyber Grind playlist
Apache License 2.0
3 stars 0 forks source link

readme

Version Licence

Cyber Grind Music Explorer

Enhanced music browser and player for Cyber Grind

CGME

Disclaimer

Formerly the main focus of this mod was to allow to play custom music in Cyber Grind, but since this part is official now CGME will be developing as a QoL mod and an enhancement of existing music player.

This mod doesn't affect leaderboards and doesn't alter your gameplay: your score will be saved

Installation

  1. Download the BepInEx release from here. It's recommended to choose BepInEx_x64 release unless you're certain you have a 32-bit system
  2. Extract the contents of BepInEx archive in your local ULTRAKILL folder. If you're not sure where this folder is located, find ULTRAKILL in your Steam Library > Right mouse click > Properties > Local files > Browse
  3. Download the CybergrindMusicExplorer archive here, then extract its contents at ULTRAKILL/BepInEx/plugins (create plugins folder manually in case it's missing)

You can also use r2modman for that. Both methods are described in the video below (click to open): Watch the video

Basics

All the basic functionality is available by pressing F4 while in Cyber Grind and ~ while in arena.

In case you forgot your CGME menu hotkey, open Audio section of ULTRAKILL options to check it.

Settings

CGME menu

All the settings for the mod are available by pressing CGME Menu hotkey (F4 by default). The main screen of the menu contains the following options:

Playback

  1. Show current track panel indefinitely: once checked, this option will make the "Now playing" panel to be present the whole time the track is playing
  2. Volume boost for custom tracks: if your track is still too quiet, you can always add up to 10dB to it. Please use it carefully
  3. Show current track alongside wave number and enemy counter: Display "Now playing" section on a big panel next to wave number and enemy counter
  4. Display subtitles: enable subtitles if present. Yes, the mod supports it, but more on that later

Playlist editing

  1. Enable tracks preview: allows to listen to 5 seconds preview of a track by clicking on it in the terminal
  2. Prevent duplicate tracks: prevents tracks duplication. Once checked, deletes existing duplicates
  3. Add downloaded tracks to playlist automatically: all the tracks that are obtained via Downloader will be added to playlist automatically

Other

Menu upscale: you can make both main and playback menus a little bit bigger

For other settings like key bindings and Themes, use the respective tab.

Playback menu

Playback menu

Allows you to switch between the tracks mid-game. Available by pressing ~ by default.

If the whole menu is an overkill for you, just switch between tracks using Next track hotkey.

Downloader

Downloader window YouCloud

You can now download tracks directly from YouTube and SoundCloud.

Downloader section supports both playlists and individual tracks URLs. All you have to do is to paste track/playlist URL in the input field and download each track individually or download every track of playlist at once. Downloaded tracks will be placed inside ULTRAKILL/Cybergrind/Music directory in YouTube and SoundCloud folders.

Note that you'll have to restart CyberGrind in order for tracks to appear in Terminal!

N.B.!

This feature uses ffmpeg. It's a 3rd-party library which you'll be offered to download automatically from the official source. You're at liberty not to do it, but in this case Downloader functionality won't be available to you. ffmpeg executables will be placed within the folder where CybergrindMusicExplorer.dll is located.

What if for some reason you can't install ffmpeg by means of CGME?

You can perform it manually.

  1. Download ffmpeg archive manually from here
  2. Open the folder ffmpeg-master-latest-win64-gpl\bin inside it
  3. Extract ffmpeg.exe and ffprobe.exe into the same folder where CybergrindMusicExplorer.dll is located. If you've installed the mod manually, it's ULTRAKILL\BepInEx\plugins\CybergrindMusicExplorer. If you're using r2modman the path is a little bit trickier: C:\Users\{YourUsername}\AppData\Roaming\r2modmanPlus-local\ULTRAKILL\profiles\{ProfileName}\BepInEx\plugins\Flazhik-CybergrindMusicExplorer\CybergrindMusicExplorer

Please also note that this feature is in early stage of development and may not work consistently.

Known issues:

Calm and battle themes

You know how in original ULTRAKILL campaign there's a light, calm theme playing when there are no enemies around, followed by an intense variation once the battle has started? Now you can enable it in Cyber Grind for original ULTRAKILL soundtrack and create your own tracks.

But unlike the campaign mode, you can decide when to play the calm theme by yourself (otherwise it would've been stupid since enemies are almost always present in Cyber Grind). Go to Themes tab and you'll see three controls:

  1. Play calm theme: disable if you're not interested in this feature
  2. Enemies threshold for calm theme to play: the battle theme will play unless there's less or equal enemies currently alive
  3. Play battle theme if more that N of these enemies are alive: enemies threshold may be a reliable way to control when the calm theme is playing, but what if, say, these two enemies who's left are Mindflayer and Insurrectionist? Is it really a good occasion to switch to the calm theme? That's why you can change a threshold for each enemy individually or disable it.

Example of the calm theme settings

"Play calm theme when there's 4 or less enemies around. Unless there's 1 or more Insurrectionists or >= 2 Mindflayers"

Alright, but what about custom tracks?

Well, to create such a track, use the same technique as for intros and loops: postfixes in your track file name. Any track is treated as a "battle theme" by default. To add its calm variation, add another, similarly named track with _calm postfix. Again, these files must have the same extension!

And what about segmented tracks? They already contain two files! How do I even make a calm variation to its intro and loop? Can I add a calm theme only to loop or only to intro specifically? Yes, you can. Customize it the way you want. Calm loop part can either have a _calm or _calmloop postfix, but intro has to end with _calmintro. More on that in the Manual section of the menu.

Segmented tracks

You can also add multi-segmented looped tracks with an intro and loop parts. In order to make such a track, place your intro and loop files in the same folder and add _intro and _loop postfixes into their file names respectively. Please note that these parts must have the same extension!

Looped track example

Like this.

If everything's been done correctly, it now should be displayed as a single track.

Looped track example numero dos

Effects replacement

Create a folder called CGME inside your ULTRAKILL/Cybergrind/Music directory (or use the one created by the mod), and you'll be able to replace some of the sound effects in Cybergrind. This folder is ignored by Music terminal. Please note that these files must have an .mp3 extension.

Here's the list of file names and the references to the sound effects these files are intended to replace:

Effects replacement

Subtitles support

If a regular Cyber Grind experience is too boring for you, you can turn it into a bloody karaoke (he-he, "bloody"). Place subtitles file named exactly as your track in the same folder where this track is located. Currently, only .srt and .vtt files are supported. The hierarchy and naming should be something like this:

ULTRAKILL/
├─ Cybergrind/
├─ Music/
│  ├─ Darude/
│  │  ├─ Darude - Sandstorm.mp3
│  │  ├─ Darude - Sandstorm.srt

Please note that if your track has into and loop segments, there must be two separate subtitles files


ULTRAKILL/
├─ Cybergrind/
│  ├─ Music/
│  │  ├─ Darude/
│  │  │  ├─ Darude - Sandstorm_loop.mp3
│  │  │  ├─ Darude - Sandstorm_loop.srt
│  │  │  ├─ Darude - Sandstorm_intro.mp3
│  │  │  ├─ Darude - Sandstorm_intro.srt

Additional Credits:

Created by Flazhik

Cyber Grind Music Explorer uses following libraries:

Extras:

For SoundCloud support, client_id was borrowed from SoundCloudExplode by jerry08, licensed under MIT License