TERRARIA CHEST RANDOMIZER!
---------------------------
v. 1.4, programmed by Arty Rogue
(works with Terraria v.1.4.5.5)
Released: 21 Feb 2026



Table of contents:
------------------

 1) What the randomizer does
 2) How to use it
   *) !! A WARNING! !!
 3) World Load
 4) Randomization Settings
 5) Item Group Controls
 6) Rarity and other details
 7) Possible modes of play to try with this tool
 8) FAQs/Why the heck won't this work?!
 9) If you find a bug...
10) Final comments



1) What the randomizer does:
----------------------------

      This program will modify (to your specification, of course) the chest
    contents of a Terraria world. There are several options to control
    the amount and types of items that get placed into the chests throughout
    your game's world.


2) How to use it:
-----------------

      You may not have seen a '.jar' file before. Basically, it's the same as an
    '.exe' file, only it requires Java to run. If you don't have Java, it's simple
    enough to get Java Run-Time installed -- just visit the following link:

        http://java.com/download 

      After downloading, you should be able to open the file by double-clicking
    it (just like an .exe file). If Java is having some weird errors and not
    bringing the program up right, it's likely some issue with your Java version
    or your Operating System that I can't really fix in a simple readme file. 
    Look around the internet for a solution or try using a different computer.
    Once the world is randomized, you can move it to another computer without
    losing the randomizer's effects (it does modify your file, after all!)

      As for the program itself, it should be easy enough to understand. First,
    load your Terraria world map with the Open dialog. Things should be
    automatically read (the map name). Everything else should be fairly intuitive:
    select what modifications you want and save the file. That's all! After that,
    just start the game up and enjoy!

     If you're having trouble, it may be that your world file is an older version.
    The Terraria devs have changed the world file format through the years, so try
    with a map generated from a current version of the game if your older worlds
    are having issues. I've tried to include a message when you load a world file
    that will warn you when the file is incompatible with the version of the
    randomizer you're using.

  ==== !!!!! A MINOR WARNING, HOWEVER: !!!!! =======================================
  |                                                                                |
  |    Use of the program will overwrite your world file! So, you really ought to  |
  | save a backup of version of your world just in case (or just in case you want  |
  | to visit your world with normal chest contents).                               |
  |    Just find your Terraria world file and make a copy of it somewhere safe     |
  | before using this tool!                                                        |
  ==================================================================================


3) World Load
-------------

    Open: Opens a Terraria world file. Everything'll stay empty until you load your
          file! Once loaded, it should read the map's name and display it in the
          'World Name' box. 
          NOTE: If you get a warning box here, your world file may not be
          compatible with the version of the Randomizer you're using! Try a map
          made from the current version of Terraria instead!

    Close: Closes an open world file.

    Save: Applies your randomization settings to the currently loaded world file.
          If there's an error in your settings (for example, all item groups are
          turned off), the tool will tell you and cancel the Save action. Fix the
          problems it tells you about and try saving again!

    Save As: The same as 'Save', but lets you rename the world file. Note that it
          current does NOT rename the world; this means loading up Terraria with
          both the previous and new files in the World directory will show you
          two worlds with the same name (and no way to tell them apart!).


4) Randomization Settings
-------------------------

    Min/Max: These let you control the number of items that appear in each chest.
          Note that you may only have a max of 40 items per chest.

    Low/Med/High: These set the Min/Max to some default values for a quick
          randomization. Low sets 2-7 items per chest, Med sets 7-15, and High
          sets 15-30.

    Item Distribution: Controls how items are selected.
       - Completely Random: 
                All items are thrown into a pot and a random one is picked per 
                item slot.
       - Unique: 
                The same as 'Completely Random', but once an item is picked from
                the pot, it cannot be picked again (unless the pot becomes empty,
                where it will refill and continue picking and removing items).
       - By Chest Type: 
                This option assumes it's being used from a freshly-generated
                world file. It looks at the first item of each chest and sets a
                'rarity' value. Depending on the rarity of the chest, the pot of
                potential items changes. Rarer chests may generate rarer items (but
                they're not guaranteed!) for each item pick.
                  For more information on rarity, check the 'Rarity Details' 
                section (6).
       - Smart Type Choices: 
                This tries to emulate the normal Terraria distribution of items.
                When checked, it will always place a certain item type (if available)
                in the first item slot of each chest. These items include accessories,
                weapons, armor, tools, and pets. All other items in the chest are
                chosen randomly afterward, with the following chances for selection:
                    1%: Another main item (weapon, accessory, tool, armor, pet)
                   50%: Crafting/building item (blocks, walls, materials, crafting
                           stations, furniture, wires/traps/carts)
                   25%: Common items (potions, coins, lighting, ammo, plants)
                   24%: Bonus items (boss summons, vanity, fine art, treasure bags,
                           banners, dyes, critters, and misc.)
                Note that currently this mode is only available for distributions
                by chest type.

    Extras: Additional controls over the main distribution options.
       - Include Wealth Chests:
                This is a new kind of chest I added for fun. When checked, there's a
                6% chance for any chest to be packed with coins/gems/stats/keys
                instead of with its normal random items. These chests lean more toward
                coins than other items in the 'Coin' category (see item groups below),
                but there's a good chance you'll find HEart Crystals, Life Fruit, and
                even biome chest keys in these chests!
       - Include Expert Mode Items:
                When checked, chests may contain expert mode items (items found in boss
                Treasure Bags in Expert Mode; those with Rainbow names). Without this
                checked, you won't see these items (or the boss treasure bags) in your
                world's chests. (Just in case you want to earn them yourself or keep
                a world strictly Normal!).
       - Include Master Mode Items:
                When checked, chests may contain master mode items (items found by 
                beating bosses in Expert Mode). Without this checked, you won't see 
                these items in your world's chests. (Just in case you want to earn them 
                yourself or keep a world strictly Normal!).
       - Include Tinkered accessories:
                When checked, chests may contain items that are combined at a Tinkering
                Station. Without it, you'll have to find the components yourself to
                combine.


5) Item Group Controls
----------------------

    Control what kinds of items are picked in your randomized chests. Want to do an all-
    Summoner run? Turn off the Melee, Ranged, and Magic weapons for items more tailored
    to you. Want to earn banners on your own? Turn 'em off and no chests will contain 'em.
    Details for each type can be seen in the 'Info' box at the bottom of the tool when
    mousing over the check box. Details for each type can also be found below.

       - Coins/Gems/Stats
             Coins, gems, max HP/MP boosting items, and keys (Golden, Temple, and Biome).
       - Accessories
             Anything that can be equipped in the accessory slot. Also includes some
             odds and ends like the Umbrella, Magic Mirror, and Breathing Reed. Does not
             include the empty Music Box (that's in Fine Art).
       - Weapons (Melee)
             Any weapon that does physical damage.
       - Weapons (Ranged)
             Any weapon that does ranged damage. Always appears with at least one
             stack of a corresponding ammo type.
       - Weapons (Magic)
             Any weapon that does magic damage.
       - Weapons (Summon)
             Any wepaon that does summon damage or summons an NPC to fight for you.
       - Armor
             Armor, including anything that goes in the equippable head, body, or leg
             slots. Does not include vanity items or items not granting a defense bonus.
       - Vanity
             Things that can be equipped in head, body, and leg vanity slots.
       - Pets/Mounts
             Pets and mounts. (pretty self-explanatory...)
       - Wires/Traps/Carts
             Wires, timers, actuators, traps, switches, minecart track, and minecarts.
             Does not include wrenches or wire cutters - those are tools.
       - Ammo/Consumables
             Arrows, bullets, rockets, and all bolts used by ranged weapons. Also has
             thorwing knives, explosives (bombs, dynamite, etc.), and other throwables.
       - Blocks
             Blocks, bricks, wood, ore, and all types of platforms. Does not include
             bars of metal or walls.
       - Walls
             Anything that can be placed as a wall (including wallpaper).
       - Tools
             Hammers, pickaxes, axes, drills, wire cutters, wrenches, hooks, painting
             tools, and fishing poles. Includes fish that acts as these tools and things
             used to place blocks like the Hive Wand.
       - Crafting Materials
             Bars, Souls, and other enemy drops that are used to craft items.
       - Crafting Stations
             Any furniture item used to craft objects (except for tables/chairs).
       - Furniture
             All furniture items like chairs, tables, beds, etc. Includes things like
             chests, vases, fountains, starfish, planter boxes, banks/safes, and doors.
       - Lighting
             Torches, lanterns, glowsticks, and anything that counts as a light source.
       - Fine Art/Music Boxes
             Paintings, statues, and music boxes. Includes the empty music box, despite
             it being an equippable accessory.
       - Plants/Seeds
             All flowers and plant seeds. Also contains sunflowers, Christmas Trees,
             mushrooms, and biome seeds.
       - Potions/Flasks
             Potions, flasks, and food that give buffs. Also includes empty bottles.
       - Dyes/Paint/Sprays
             Dyes, Hair Sprays, and paints. Also includes items used to make dyes (this
             includes strange plants).
       - Critters/Fish
             Critters catchable with a bug net or in bottles/terrariums.
       - Boss Summons
             Items that summon bosses or events (like the Solar Tablet). Does not include
             materials that can be crafted to create these items (like Solar Tablet 
             Fragments).
       - Banners
             Banners that normally get awarded for killing many of the same enemy. Also
             includes boss trophies. Does not include fishing trophies (like the sailfish
             or goldfish trophies).
       - Treasure Bags/Crates
             Crates and treasure bags from expert mode/holidays. Also the Herb Bag.
       - NPC
             Odds and ends that don't fit into other categories but are sold by NPCS.
             This includes stuff from the Party Girl, Golfer, and others like golf clubs,
             streamers, and town pet items.
       - Christams
             Items used to decorate a Christmas Tree.
       - Misc.
             Anything that didn't really fit in other categories. Stuff here includes
             powders, Christmas Tree decorations, Party Girl stuff, rope, large gems,
             gravestones, buckets, and garbage (tin can, coal, etc.).


6) Stack Quantity Multiplier
----------------------------

    This field multiplies the default item stacks for some items by the provided number.
    While it won't affect things that can't be stacked (liked weapons or accessories),
    it can provide some extra blocks, ammo, furniture, etc. Useful for when you may be
    hosting multiple players to ensure everyone gets a decent amount.
      Do note that currently the stack size maxes at 9999, so numbers provided above that
    will set the stack count to 9999.


7) Rarity and other details
---------------------------

    Quantities:
        Each item type has a different stack amount depending on its type. I tried
        to make sure each had a modest amount -- not too much and not too little.
        For example, ammo usually comes in stacks of 80-300, bars come in stacks of
        10-50, blocks come in stacks of 80-150, and walls in 150-400. Weapons that
        can be stacked like the Light Discs may spawn in stacks as well.
          If you want to change the stack amount yourself, I suggest downloading
        the source and looking for the 'itemList.txt' in the project's resources.
        The fourth column in that file controls the item stack for each row's item.
          Note that the stack quantities may be further modified with the Stack
        Quantity Multiplier. Check that section above for more details on how that
        works.

    Rarity:
        I've tried to split up the rarity of items based on when the normal player
        can craft/attain the item. The rarity levels are below.
          (After-the-fact, I realized I should have used the item font color, but 
        after going through 3600 items by hand once, I didn't want to do it again, 
        this time looking up which items were which colors....)

        Level 0: Beginning to Underground
        Level 1: Underground to breaking Orbs (includes goblin invasions)
        Level 2: Defeat of Eater of Worlds/Eye of Cthulhu to end of dungeon (+sky)
        Level 3: Jungle, the dungeon, and making it down to Hell
        Level 4: Hell through the beginning of Hard mode (including Cobalt items)
        Level 5: Mythril through defeating one mechanical boss (+eclipse, pirates)
        Level 6: All 3 mechanical bosses beaten through beating Plantera
        Level 7: Hard mode dungeon, festive moons, Martian Madness
        Level 8: Lunar event and Moon Lord drops, as well as everything afterward

    Chest Rarity:
        Chests start with their rarity gauged from the first item contained inside
        them before randomizing and their X/Y coordinates. Each chest has a chance
        to increase their items' rarity as well (see after the rank lists). A chest
        rank corresponds to an item's rarity level. Thus, Rank 1 chests will most
        often spawn items normally found between the beginning of the game to 
        breaking shadow orbs.
          Note that Smart Type Choices will try to make the main chest item (the
        accessory/weapon/armor/pet) equivalent to the chest's rarity. This means
        a Rank 5 chest should always have a Rank 5 main item, not a Rank 0-Rank 5
        like all other items in the chest. If no items of a certain Rank are
        available, the next lowest level will be tried (and so on until an item is
        selected).
          Anyway, here are the ranks. Note that Mahogany, Granite, and Marble chests
        are all equivalent to Golden Chests.

        Rank 0: Wooden (non-dungeon)
        Rank 1: Golden (top level)
        Rank 2: Ice, Water, Golden (mid level), Wooden (dungeon)
        Rank 3: Ivy, Skyware, Living Wood, Golden (lava)
        Rank 4: Pyramid, Golden (dungeon), Golden (deep lava)
        Rank 5: Web-covered, Shadow
        Rank 6: Lihzahrd, Biome
        Rank 7: (upgrade only)
        Rank 8: (upgrade only)

        Upgrade chances:
            70% - No upgrade
            20% - +1 Rank
             6% - +2 Ranks
             3% - +3 Ranks
             1% - +4 Ranks

        Golden Chest Depth guide:
                       small        medium        large
                       --------------------------------------
            top:       0-580        0-950         0-1330
            mid:       581-700      951-1200      1331-1700
            lava:      701-850      1201-1400     1701-1950
            deep lava: 851-1200     1401-1800     1951-2400


    Wealth Chest chances:
        50% - Coin; 20%/30%/40%/10% chance for copper/silver/gold/platinum coins
        23% - Gem
        15% - Stat increaser (Mana Star, Life Crystal, Life Fruit)
         5% - Key; 90% of the time is a gold key, 10% is a temple key
         5% - Biome key
         2% - Pearls


    Weapon/Accessory modifiers:
        Have a 50% chance to be given to any relevant item, theoretically.
        Item types should be limited in the normal modifiers, but one or two
        special cases may have normally unobtainable modifiers on them.


7) Possible modes of play to try with this tool
-----------------------------------------------

    Why randomize chest data, you ask? To make for interesting new ways to play the
    game, of course! Here are a few that I've come up with to put a new spin on
    your Terrarian adventure! Combine them for even crazier modes of play!

      - Beast of Burden
           Never store any items, including in portable storage (banks/safes). If
           you need inventory space, you must trash an item from your inventory.

      - Luddite
           Don't craft items or buy items from vendors. Rely entirely on what the
           chests have for you!

      - Unselfish
           Only take one item from each chest. Choose from your options wisely!

      - Trendy
           Use everything you possibly can in each chest you find. Gear and weapons
           will be swapped as soon as you find another item in those slots, so
           make sure you want to chance opening that next chest before the next boss
           fight!

      - Conservative
           Limit yourself to a certain number of chests before taking on each boss.
           For example, give yourself only 3 chests before fighting the Eye of
           Cthulhu, 6 before the Eater of Worlds, etc.


8) FAQs/Why the heck won't this work?!
--------------------------------------

    Q) Where do I find my Terraria world files?
    A) I don't know exactly where they are kept on all operating systems, but on
       my Windows 10 box, they're found at:
           C:\Users\<my user name>\Documents\My Games\Terraria\Worlds\
       If you can't find them there, consult the Googles to see where they may be!

    Q) My game won't work after applying the randomizations! Wat do?
    A) There must have been an error writing to save data. Either load your backup
       and try randomizing again or try some different options. I'd love to hear
       about what settings may have caused your error; shoot me an e-mail (see below)
       with your settings and I may be able to fix it!

    Q) Why won't Java work?
    A) I don't know -- I didn't write Java. Thus, I really can't help troubleshoot
       much. Maybe Google can help?

    Q) Can I take a look at your source code?
    A) Sure can! I'm planning on putting the source code up online soon. Check the
       site you (should have) downloaded this from for a link to the code.

    Q) I have some suggestions for improvement! Want to hear them?
    A) To be truthful, I'll probably not be working much more on this tool (unless
       a crazy new version of Terraria comes out). If you wish to try and add some
       new funtionality to the tool, try downloading the source code when it's out
       to try makin' your new changes!


9) If you find a bug:
---------------------

      Please report it to me! I tried a bunch of different options and fuzz tests.
    Everything seemed fine, but something may have slipped through the cracks. If you
    find something that broke the program, shoot me an E-mail at:

       Artemis251(at)yahoo.com

    with the title mentioning something about the Terraria Chest Randomizer. I'm
    kinda busy a lot of the time, but I may be able to fix the issue and get back to 
    you, assuming it's not a Java issue and it's not covered in the FAQ section of this
    Readme.


10) And so...
-------------

      I think that about wraps it up! Enjoy, and I hope you have a blast creating new
    ways to play the game!
