[Explanation] Treasure Classes

[eezstreet]

Treasure Classes are not physical, tangible things that can be seen ingame. Rather, they are conceptual means of organizing data for random number generation.

 

A treasure class contains one or more treasure class/item, and the "odds" of that treasure class/item being picked. Each item automatically generates a treasure class with itself in it.

A few basic examples can explain this concept fairly easily:

• Trandoshan Pistols: Includes the Trandoshan Pistol with odds 1 and Advanced Trandoshan Pistol with odds 3
• Stormtrooper Rifles: Includes the E-11 Rifle with odds 5 and the E-11 Carbine with odds 3
• Stormtrooper Arms: Includes the T-21 with odds 1 and the Stormtrooper Rifles class with odds 8

Now let's say we want to spawn 20 Trandoshans. Statistically speaking, around 15 of those will have the Advanced Trandoshan Pistol and 5 will have the regular one. This is because the Trandoshan Pistol has a 1/4 chance of showing up, and the Advanced version has a 3/4 chance of showing up.

Composition:

• 15 with Advanced Trandoshan Pistol
• 5 with Trandoshan Pistol

 

Stormtroopers on the other hand are a bit different. Let's say we want to spawn 90 of them. Statistically speaking, you should have 10 of them spawn with the T-21, and the remaining 80 should pick either the E-11 Carbine or the E-11 Rifle. The carbine would spawn 3/8 times and the rifle would spawn 5/8 times. The composition would wind up looking like this:

• 10 with T-21 Repeater
• 30 with E-11 Carbine
• 50 with E-11 Rifle

 

Not only can this apply to what weapons an enemy can be wielding, but it can also apply to things like containers, vendor loot, and more. Here are some practical examples:

• Mos Eisley Urchin: Desert Junk (15), Small Ammo Item (2), Small Aid (4)
• Transit Ship Luggage: Passenger Junk (20), Small Aid (5), Holdout Weapon (1), High-Class Attire (2), Commoner Attire (5), Common Lightsaber Crystal (1)

[Silverfang]

Expanding upon the Trandoshan example, they would also spawn rarely with LS-180 Heavy repeaters and Bowcasters, but more commonly with ACP Shotguns and LT-60 carbines.

 

As another example a sniper Trandoshan class might spawn most often with a "Hammer of Shirke" ACP sniper rifle, but may also sometimes spawn with a scoped heavy bowcaster.

[eezstreet]

A treasure class can also have properties associated with it:

• picks: The number of items which are picked from the treasure class. Note that if you nest treasure classes, the topmost one is the one that determines the number of picks.
• repeat: Specifies whether the same item can be picked more than once.

Treasure classes require some care in designing, because it is possible that they can cause errors:

• Stack overflow can occur if you have a treasure class somehow including itself. For instance, if "Blasters" treasure class includes "Blasters" in it somehow, you can have infinite recursion and thus crash the server. You can also get it with very highly nested treasure classes (> 100 levels deep).
• Infinite loops can occur if the "picks" is set higher than the total number of items that can drop, and the "repeat" flag is turned off. Example: an NPC always carries 6 different items, but their treasure class only indicates them having 5 items. These will cause the server (or the client) to freeze, but not crash.

[Futuza]

 

 

• Stack overflow can occur if you have a treasure class somehow including itself. For instance, if "Blasters" treasure class includes "Blasters" in it somehow, you can have infinite recursion and thus crash the server. You can also get it with very highly nested treasure classes (> 100 levels deep).
• Infinite loops can occur if the "picks" is set higher than the total number of items that can drop, and the "repeat" flag is turned off. Example: an NPC always carries 6 different items, but their treasure class only indicates them having 5 items. These will cause the server (or the client) to freeze, but not crash.

 

Does it actually crash the game or do you just mean you will get an error that says something like "Warning, bad treasure class - disabling object, etc."?  Cause crashing server is no good, should at least do some basic checks and not let stupid server owner do stupid things.  Since these things are going to be setup via some sort of json cfg file right?

[eezstreet]

Both can be checked.

 

For the former, you'd have to run a hashing function on every single treasure class/item that a TC includes. Since treasure class resolution is lazily evaluated, you'd get lag spikes during gameplay. I wouldn't recommend checking this one - it's rare that you'd even get an error from recursive treasure classes.

 

The second one is easy to check. Just count the number of items that can drop.

[Futuza]

Both can be checked.

 

For the former, you'd have to run a hashing function on every single treasure class/item that a TC includes. Since treasure class resolution is lazily evaluated, you'd get lag spikes during gameplay. I wouldn't recommend checking this one - it's rare that you'd even get an error from recursive treasure classes.

 

Why not run the hashcheck once during startup?  Since the user probably isn't going to be editing Treasure Class files while the game is running.

[eezstreet]

I am considering that as a cvar: jkg_tcstackguard (latched CVAR). Slows down initial start up, but guarantees that the files will be stack-safe.

[eezstreet]

I am happy to report that the Treasure Class system is fully coded and I have some screenshots to show of the math behind it.

 

For starters, here is the format of the new treasure class files (this one is called ext_data/treasure/test.json):

 

{
"classes": {
    "base": {
        "numberPicksMin": 1,
        "numberPicksMax": 5,
        "picks": {
            "high-quality": 1,
            "med-quality": 4,
            "junk": 10
            }
    },

    "high-quality": {
        "numberPicksMin": 1,
        "numberPicksMax": 1,
        "picks": {
            "launcher_W-90": 4,
            "chem_CR-24": 7
        }
    },

    "med-quality": {
        "numberPicksMin": 1,
        "numberPicksMax": 1,
        "picks": {
            "rifle_E-11": 8,
            "carbine_E-11": 12,
            "Mine_LaserTrip1": 2
        }
    },

    "junk": {
        "numberPicksMin": 1,
        "numberPicksMax": 1,
            "picks": {
                "pistol_Suppressor": 5,
                "pistol_DL-18": 3,
                "pistol_Q2": 4
            }
    }
}
}

 

Each treasure class .json file can have multiple treasure classes inside of it. Treasure classes are case insensitive. Also this means now that item names will be case insensitive going forward.

I have created a tcEval command which performs actual simulated drops. Here is me simulating 100 drops of the `base` treasure class:

 

 

 

 

(note: the console currently can't render the '%' correctly, so it shows as a '.')

Also note that the `base` treasure class only picks 1 item from it, instead of 1-5 as listed in the treasure class file. This is currently something that I am working on.

[eezstreet]

On close examination, those values in the screenshot are wrong. Turns out there was an off-by-one error producing incorrect drop rates.

Here are the correct drop rates:

 

 

 

 

And as a bonus, I added a new command (tcEvalMulti) which turns on the multi flag for treasure classes when evaluating them: