Getting Started

0. Creating your Challenge File

Creating a new basic challenge with the BU-CB system is quite quick and easy. For this guide I will be referencing the existing challenge "Load Bearing". To start, simply create a file with the name of the challenge and the .lua extension, such as load_bearing.lua. For now, it does not matter where the file is located.

To begin creating your challenge, you will need to open the file in whatever code editor you normally use. If you do not have any installed, you may install VIM here, or perhaps easier for unfamiliar users, Visual Studio Code here.

Once your file has been opened within your favorite editor, you may paste in the preset challenge structure as follows:

local Challenge = {}
Challenge.NAME = "Template"
Challenge.DESIGNER = "USERNAME"
Challenge.DATE_CREATED = 240625 --Y/M/D
Challenge.VERSION = "1.0.0"
Challenge.DATA = {
  rules = {
    custom = {
    },
    modifiers = {},
  },
  jokers = {},
  consumeables = {},
  vouchers = {},
  deck = {
    type = "Challenge Deck",
  },
  restrictions = {
    banned_cards = {},
    banned_tags = {},
    banned_other = {},
  },
}

return Challenge

This may look scary at first if you're unfamiliar with code, but it's actually all very simple. Now that you have the template for a challenge pasted in, we can begin modifying it to our desire.

1. Basic Information

At the top of your Challenge file, you will see the following fields:

Challenge.NAME = "Template"
Challenge.DESIGNER = "USERNAME"
Challenge.DATE_CREATED = 240625 --Y/M/D
Challenge.VERSION = "1.0.0"

Each one of these is a primary identifier for what the challenge is. The first thing you should do when creating a challenge is to input it's name (even if its a work in progress), input whatever username you'd like to use to identify you as its designer, and give DATE_CREATED a value corresponding to the date it was created. In this example, the provided date was the 25th of June, 2024 (24(Y)/06(M)/25(D)). The Version is unimportant for this case and may be left as is.

2. Challenge Rules

This is perhaps the most important part of creating a challenge- implementing whatever custom challenge rules you would like. The base game has a few modifiers you can use, and BU-CB provides you with many more to choose from as well.

To begin with, we will address the custom = { portion of the rules. In order to implement a new rule, you must define a new id, and in some cases, hand it a value. In our Load Bearing challenge, I'm going to implement a rule called cm_force_hand and give it a value of Straight, which looks like this:

rules = {
    custom = {
      { id = "cm_force_hand", value = "Straight" },
    },
    modifiers = {},
  },

That's all you have to do to implement a custom rule! Make sure to put a comma after every rule you add, as lua is very strict with putting commas in a lot of places. I am also going to add cm_all_facedown for fun, which looks like this:

{ id = "cm_all_facedown },

The full list of custom rules, their values if they need one, and their effects are as follows:

Rules	Values	Effect
all_perishable	None	All jokers are Perishable
all_rental	None	All jokers are Rental
cm_force_hand	Handname string	Played hands must contain the handname
cm_negative_interest	None	Interest loses you money
cm_no_overscoring	Integer	You lose if you score over (Value/100)x the blind
no_shop_planets	None	No planet cards in the shop
no_shop_tarots	None	No tarot cards in the shop
cm_scaling	8 string integers	Ante scaling follows the specified values
cm_noshop	None	The shop will never appear
cm_hand_kills	Handname string	Lose if played hand contains handname
cm_all_facedown	None	All Jokers, Tarots, Planets, Spectrals are facedown
cm_soul_luck	Double	Soul card chance becomes 1-value rather than 0.003
cm_repeat_bosses	None	Bosses may repeat
no_reward	None	blinds dont give bonus money
no_reward_specific	String, 'Small', 'Big', or 'Boss'	Specified blind doesnt give bonus money
no_interest	None	No interest
no_shop_jokers	None	No jokers in shop
no_extra_hand_money	None	hands don't give money during cashout

3. Modifiers

Similar to custom rules, modifiers change some of the values of your challenge. Adding these in is very similar to custom rules, except we operate in the modifiers = { field. I'm going to reduce the starting discard value to 2 in my example challenge, which looks like this:

modifiers = {
{ id = "discards", value = 2 },
},

Simple as that! You can do this for many of the games basic starting values, as described in the table below.

Modifier	Value	Effect
discards	integer	sets the starting discards
hands	integer	sets the starting hands
dollars	integer	sets the starting dollars
reroll_cost	integer	sets the starting reroll cost
joker_slots	integer	sets the starting joker slots
consumable_slots	integer	sets the starting consumable slots
hand_size	integer	sets the starting hand size

4. Jokers, Consumables and Vouchers

Another of the most important aspects of a challenge is your starting position- what jokers, vouchers and consumables do you begin with? You can set all of these quite easily in your challenge file as well. In my example challenge, I'm going to give ourselves Omen Globe, negative eternal Sixth Sense, and a starting Cryptid card. This looks similar to our previous additions as well:

jokers = {
{ id = 'j_sixth_sense', edition = 'negative', eternal = true },
},
consumeables = {
{ id = 'c_cryptid', edition = 'negative' },
},
vouchers = {
{ id = 'v_omen_globe' },
},

Edition modifiers are either 'negative', 'holo', 'polychrome', or 'foil', as expected. In order to set a joker to rental or perishable, it is the same as eternal- just a simple "perishable = true" works within the BU-CB mod, though it wont work in vanilla. I can't list every id for these values in this guide, as it would be too far too long, though you can find them elsewhere in the wiki.

We aren't limited to adding just one of these items, you can add as many different (and the same) items in these fields as you want, though stacking too many of a voucher or a joker may have unintended consequences. Now that you've added custom rules, modifiers, jokers, consumables and vouchers to your challenge, we are on to the last 2 steps: Deck and Restrictions.

5. Customizing your Deck

A lot of the time, you won't want or need to change anything about the default deck, in which case you can ignore this section entirely and move on to restrictions. However, in creating more complicated or gimmicky challenges it can be useful to have a customized deck. We are going to do this by adding a cards = {field into our deck = { field. This looks like the following:

deck = {
    cards = {},
    type = 'Challenge Deck'
},

After you have done that, you can manually add whatever cards you would like into the deck. card formats work in a few segments: the suit s, the rank r, the edition e and the seal g. You only HAVE to include the suit and rank values, and may add edition and seal if you want them on a card. I'm going to create a deck that starts with 5 glass red seal king of hearts in my example challenge, which looks like this:

cards ={
    { s = 'H', r = 'K', e = 'm_glass', g = 'Red' },
    { s = 'H', r = 'K', e = 'm_glass', g = 'Red' },
    { s = 'H', r = 'K', e = 'm_glass', g = 'Red' },
    { s = 'H', r = 'K', e = 'm_glass', g = 'Red' },
    { s = 'H', r = 'K', e = 'm_glass', g = 'Red' },
},

Suit and Rank values work as expected, but listed below are the Edition and Seal values to use:

Edition	ID
Glass	'm_glass'
Wild	'm_wild'
Steel	'm_steel'
Stone	'm_stone'
Lucky	'm_lucky'
Gold	'm_gold'
Mult	'm_mult'
Bonus	'm_bonus'

Seal	ID
Red	'Red'
Gold	'Gold'
Blue	'Blue'
Purple	'Purple'

With a custom deck created, we can finally move on to the last step: Restricting your challenge.

6. Restrictions

In creating challenges, we can ban whatever we like from appearing within our game. If I wanted to ban every single joker except Jimbo, I could (though that would be a lot of typing). Banning consumeables, jokers, vouchers, bosses, booster packs, and even Boss Blinds is a similar process to what we've been doing previously, though they are broken up into categories. We will start with the banned_cards section of the restrictions.

As before, we will ban through the use of a { id = '' },statement. Banning jokers uses the exact same statement as adding them, and this is true for tarots, planets, and spectrals as well. Something we can also do when banning cards is to ban Booster packs, which have their own ID's. I'm going to ban all the tarot packs from my example challenge, which looks like this:

banned_cards = {
    { id = "p_arcana_normal_1"},
    { id = "p_arcana_normal_2"},
    { id = "p_arcana_normal_3"},
    { id = "p_arcana_normal_4"},
    { id = "p_arcana_jumbo_1"},
    { id = "p_arcana_jumbo_2"},
    { id = "p_arcana_mega_1"},
    { id = "p_arcana_mega_2"},
},

There is a way to package these so that the restrictions tab in game only shows 1 pack but bans everything, though I'm going to ignore that for the sake of simplicity in this guide. You may ban cards in any order you want, so dont worry about switching between banning jokers, packs, tarots etc if a challenge is just for personal use. However, if you'd like your challenge to be added to the mod, it is helpful for them to be ordered in groups for both dev and player understanding.

Moving on to the banned_tags section of the restrictions, we can do the same here. For the sake of brevity I'm going to avoid listing out more examples of the same thing- the id's for the skip tags can be found listed elsewhere in the wiki, though they generally match the tags in-game name.

Finally, the banned_other section of the restrictions is used to ban bosses primarily. This is done in the exact same way as previous, though 'other' bans have an additional requirement, the type field. Banning a boss looks like this:

banned_other = {
{ id = 'bl_ox', type = 'Blind' },
},

And that's it! Many of these areas may be left unchanged in your challenge, and that's ok- not every challenge is going to use every feature available. Now you can go create most any challenge you would like with the BU-CB mod and its capabilities. Once you are done with your challenge, just drag it into the BU-CB/Challenges folder which contains all preexisting custom challenges. Have fun!