Shieldmodding by Discookie

Docs

Introduction

This general guide is targeted towards installers and users of the Insane mod created by Discookie. I broke it up into smaller sections, listed in the Table of Contents.
While the Installation's write-up is pretty straightforward, the end of Modding, and the Technical background are much more complex.
So, enough rambling, let's get started!

Table of Contents

  1. Introduction
  2. Table of Contents
  3. Description
  4. Installation
  5. Difficulty and other modifications
  6. Technical background
  7. Links and acknowledgements

Description and Features

The Insane mod was originally created with the goal of making maps harder while keeping them 100%-able. Since then I have extended the list of features quite a bit:

  • Static seeds - so you don't have different maps every time you restart
  • Reversed doubles - so you can cross your hands more often
  • Advanced distance limiting - so you don't have to move your hands at 1000 m/s
  • Better difficulty options - so you can kill your hands without making the game impossible
  • Difficulty calculator - so you know how hard you're on yourself
  • Automatic update checker - so you can get the latest features quickly
  • Git support - so you can send me things you did! Access it here!

While I'm focusing more on custom maps, I still plan to include new features in Insane. Some of these upcoming features:

  • Non-centered doubles - so you don't always have to face the same way (out now on Dev!)
  • Strength-dependent colors - so you can really feel the beat drop
  • Strength-dependent difficulty - so you can chill when your song does
  • Overlapping holds - so you can hit things while holding things
  • Curved holds - so you can move your hands while holding things
  • Leaderboards - so you can compete with other people
  • Custom distance limiting - so you can write things to make it faster/weirder (out now on Dev!)

There are 2 separate releases: Stable, and Dev. My reasoning for this, is that I don't have a VIVE. I'm developing these versions blindly, but if you'd like to help me test those, feel free to download the Dev branch!
Don't forget to give me feedback when you do get around to test these!

Installation

For the Stable branch:

  1. Download the file.
  2. Open it with 7-zip or equivalent.
  3. Backup the folder you're abot to extract to!
    (otherwise you'll lose your current mod)
  4. Extract it to one of your mod folders.
    For example: (steam dir)/Audioshield/mods/Hard ShieldVR
    • If you haven't extracted into Hard ShieldVR, rename Hard ShieldVR.lua to (your folder name).lua.
  5. Test your stuff! You'll see the different How To Play screen if you installed correctly.
  6. If the mod's too hard, see the next section!
  7. If you're still pondering the meaning of life while reading this, check out these important videos.

For the Dev branch:

  1. Download and extract the file.
  2. Read the README included!
  3. Run the file make.bat.
  4. Copy the output folder's contents into your mod folder.
  5. Something's wrong? Open an issue on GitHub, or adjust the settings as described in the docs!

Difficulty and other modifications

Important - If you want to keep your difficulty rating up-to-date on the how-to-play screen, do both steps!
This section only applies to the Stable branch!
Now that it's out of the way, there are several ways you can alter the difficulty, here in recommended order of priority:

  1. The notes are coming too slowfast, I can't move my hands in time!
    Solution: Modify the maximum acceleration!
    The higher the value, the faster your hands go.
    • In the LUA file, modify the maxAccelLeft and maxAccelRight values!
    • In dynamic/diff.js, modify the maxDiff value!
             Default: 7, Recommended range: 4-16, Linear scaling

  2. The notes are too dense!
    Solution: Modify the note spacing!
    The lower the value, the denser the notes.
    • In the LUA file, modify the minNoteSpacing value!
    • In dynamic/diff.js, modify the trillDiff value!
             Default: 0, Recommended range: 0-0.2, Linear scaling

  3. I'm seeing too many doubles!
    Solution: Modify the double-notes chance factor!
    The higher the value, the more double-notes.
    • In the LUA file, modify the doubleFactor value!
    • In dynamic/diff.js, modify the multiDiff value!
             Default: 0.2, Recommended range: 0-1, Linear scaling

  4. The notes are too far apart, I can't hit them!
    Note: Scales the difficulty the same way as 1.!
    Solution: Modify the armspan scale!
    The higher the value, the larger the armspan is, the faster your hands go!
    • In the LUA file, modify the impactX_Scaler value!
    • In dynamic/diff.js, modify the armspan value!
             Default: 1.7, Recommended range: 1-2, Linear scaling

  5. It's fairly slow, but I'm still very tired!
    Note: Shouldn't change this, in most cases changing 1. is better!
    => Solution: Modify the acceleration factor!
    The LOWER the value, the faster the average acceleration is,
      but max acceleration stays the same!
    • In the LUA file, modify the factAccelLeft and factAccelRight values!
    • In dynamic/diff.js, modify the avgDiff value! Note: additional step in the file
             Default: 0.6, Recommended range: 0.1-1, Exponential scaling!

Further modifications coming soon!

Technical background

As I spent countless hours watching Audioshield streams, I noticed something: no matter how hard streamers try, or how high the min note spacing is, they cannot 100% fast maps. At first I thought this was due to them not being good enough, but then, as I started to look into modding, I had the idea to make a quick Excel chart:

Random positions and acceleration
A plot of the default hand position generator. Sometimes you have to move your hands faster than 1000 m/s to hit them!
1 unit ≈ 1 meter

Do you notice anything?
Now, if you look real closely (or click on the image to enlarge it), you'll see that there are a few impossible notes, where, even if you saw the notes and reacted in time, you still had no chance to hit them.
To put this into perspective, here is a logarithmic plot of the same values:

Random positions on a log scale
The same plot as above, but with a log scale.

This is pretty damn fast.

So how do you battle this?

Limit the note distance.
This creates a lot of questions, the most important is how you limit it.

Limit x=xt0: Audioshield's current solution to this problem is to limit the maximum distance between notes to a constant, independent on note timing. This works great if your notespacing is large, but fails pretty hard when you play with the notespacing of the 2 mods listed in the Links section.

Limit v=xt1: The other approach is to limit the note distance based on time. This is what should have been done in the first place, instead of Audioshield's approach, for the base mods. (Flatlander's mod uses this method.) This doesn't leave much room for difficulty based on these values, so I went a step further from that.

Limit a=xt2: What I went with in the end is limiting the acceleration of your hand. This is the natural limit of your hands, since acceleration takes most of the energy of moving them. The downside is streams - notes in extremely quick succession. They will be made too easy.

In the end, I did nothing special on top of limiting acceleration, so I went with: r·t2
r is random (more later), t is time between notes

Now, onto the more interesting part: the random.

With the default random generator, you would have a linear scaling for note distance - great for casual players, not-so-great for an acceleration-focused mod. So to battle this, I basically went ahead and created a weighted random generator.

The algorithm for that is: m·rf+n
n is minimum, m is maximum, f is factor, r is a random number

This has a few caveats: you need to give it a positive random (otherwise you wouldn't have a real solution), and if n≠0, you would have cases where there are no possible solutions within the gameplay bounds. The value itself is there, and there's an option to change it, but changing it currently breaks the generator algorithm.

Aside from that, this algorithm is great for dynamically limiting a) the maximum acceleration, and b) the average acceleration. Because f isn't dependent on m, you can tire yourself out, while making it still 100%-able for yourself. It is better than the previous approach, because it is biased towards notes being further apart, thus making them harder to hit.

Double notes were interesting: They posed a challenge, because the current system is built around symmetrical doubles - not good for limiting! I did not solve this problem (the only way to solve is to implement non-centered doubles), but I made it more bearable by letting the game flip the doublenotes' colors.

TLDR: Acceleration limit, weighted random, too much free time...

And the result:

A plot of my generator. The hand's acceleration never exceeds 6 units/s²

Much better.
Note: The acceleration's average should be somewhere around 4.3 - it isn't, because of the way I created notes inside Excel.
The spreadsheet is available here.

Links and acknowledgements

This all wouldn't have been possible without Ruirize! Thank you for putting up with my endless buggery and failed pushes, and thank you for initial testing! Check out LIV, a mixed reality tool he's helping develop!

Special thanks to Zekses and Flatlander who put up with my endless rambling and helped bring some ideas to life! Check out their mods: Zekses' fork and Flatlander's mod!

Also don't forget about previous mods of the game such as Even Harder and Expert! This all wouldn't be possible without you! (literally, because I wouldn't have access to the mods :> )

And last, but not least, the game itself: Audioshield! And its developer Dylan!