Do things seem broken? We are currently working on streamlining the permission system and its backend. Please be patient!


Adding Upgrades

Last edited by MichaelTheShifter on 4/6/2017 7:41:09 PM

Adding Shiftorium upgrades is quite easy using the modern engine. I'll walk you through it.

Firstly, let's disambiguate something.

In the ShiftOS solution, you'll notice that there are two Shiftorium.txt resources in the game - one in ShiftOS.Engine, and another in ShiftOS.WinForms - you want to focus on the ShiftOS.WinForms one.

The engine version of this file is not used and only kicks in when there is a syntax error in the correct Windows Forms file.

The Definitions File

So, this is quite simple. In the Solution Explorer, locate your Shiftorium.txt - and open it.

You'll notice that this file is a JSON file. It is a list of objects. This is called a Shiftorium Definitions File. It tells the ShiftOS engine all the purchaseable upgrades that should be displayed in the engine. It tells the engine how much each upgrade should cost (in Codepoints), what the upgrade is called, its description, its category (see Shiftorium Categories for details) and its dependencies.

It uses these details to create a list of upgrades the user has already installed, upgrades the user can buy, and upgrades that depend on not-yet-installed upgrades.

Dependencies and Shiftorium Upgrade IDs

In ShiftOS, if you were to visualize the structure of the definition list as a diagram, you would see a web with inter-connecting nodes. Each node is an upgrade. The reason this would occur is because upgrades depend on eachother. For example, you can't save files in TextPad without File Skimmer, and you can't have an app launcher entry for File Skimmer without the App Launcher itself and File Skimmer itself.

Declaring dependencies can be slightly confusing, but fear not, I'll help you out.

First, let's discuss shiftorium upgrade IDs.

When you name your upgrade, the engine automatically assigns your upgrade with a code-friendly identifier. This identifier is used by the engine to:

  1. Track upgrade installs in the save file - only the upgrade ID and a boolean determining whether the upgrade is installed is stored in the save.
  2. Allow localization of the upgrade name without affecting the code - MUD Fundamentals could be written in various languages, but mud_fundamentals can't. It is used by the code and therefore can't be localized without having a new version of ShiftOS for each language.

Upgrade IDs are typically the English name of your upgrade, in all lowercase, with spaces replaced by underscores. For example, AL File Skimmer becomes al_file_skimmer.

Dependency strings

When adding your upgrade, you'll want to declare a dependency string. This is simply a semicolon ; separated list of all upgrades (in their ID forms) that your upgrade depends on.

For example, AL File Skimmer's dependency string is file_skimmer;app_launcher, while Clock Minutes has a dependency string of clock.

Actually adding the upgrade to the definition list.

Still got that Shiftorium.txt file open? Awesome. Let's create a new upgrade, shall we? First, choose a name for your upgrade. Use 1 to 4 words maximum.

We'll go with "Desktop Widgets" for the example upgrade.

Next, choose a fair Codepoint cost for your upgrade. Be respectful to your customers! Don't charge a thousand Codepoints for an upgrade that simply adds a Terminal command.

We'll go for 2000 Codepoints, as Desktop Widgets would be considered pretty powerful for the user experience.

Next, describe your upgrade! The upgrade description tells users what they're buying. Try to describe your upgrade as best as possible in one to three sentences.

Next, categorize your upgrade based on what it extends. You can add your own category, but the main ones are:

  1. Kernel & System
  2. GUI
  3. Enhancements
  4. Applications
  5. Customization

We'll go for the GUI category for our upgrade.

Lastly, we need a dependency string. If your upgrade is intended to be bought at the beginning of the game and doesn't depend on other upgrades, you can skip this step. Dependencies are optional.

But, our upgrade depends on WM Free Placement, Skinning, and Desktop. So, our dependency string will be desktop;skinning;wm_free_placement.

Now it's time to actually write some JSON.

It doesn't matter where in the list you add your upgrade - the engine takes care of constructing the upgrade tree properly.

Simply add this JSON:

    Name: "Desktop Widgets",
    Cost: 2000,
    Description: "Desktop Widgets give you the ability to add small applets to your desktop that can show important information like CPU performance, RAM usage, hard drive activity, and various other pieces of info.",
    Dependencies: "desktop;skinning;wm_free_placement",
    Category: "GUI"

Remember to replace the above values with your own values!

Once you've added the object, simply save the file, compile and run ShiftOS, and type shiftorium.list in your Terminal. If you have the dependencies, your upgrade ID should show in the command output, followed by the cost in CP you provided.

You can then use this ID in other Shiftorium guides to determine if the upgrade has been installed, start stories on upgrade install, etc. But, that, young Shifter, is all for this guide.