Overview
This guide is the documentation for yaEID’s API. It explains the functionality and has code examples and accompanying screenshots to help you create your own external description expansion mods.
General Documentation
The yaEID API has 1 important class and 4 useful functions to create and register instances of that class.
DescriptionEntry( id, variant, description, image )
Number id is the relevant ID number of the collectible, trinket, card, or pill effect
Number variant is the PickupVariant value for the pickup being described
String description is the actual description text (n new line character supported)
Boolean image is for utilizing images as descriptions (in the case of non-English like translations)
If image is true, description should instead describe the relative path of the image to be drawn.
To use the image “mod/resources/gfx/mushroom.png”, the description should be “gfx/mushroom.png” and image should be set to true
The main function to register entries:
YAEID:RegisterDescriptions( * key, Table entries )
The four functions below are convenience functions to make registering descriptions a bit easier by passing the proper variant in as the key for you.
YAEID:RegisterCollectibles( Table entries ) YAEID:RegisterTrinkets( Table entries ) YAEID:RegisterCards( Table entries ) YAEID:RegisterPills( Table entries )
entries is a table of tables. The table listed in entries describe how to build a DescriptionEntry.
{ Number id, String description[, String languageCode] }
If languageCode is ignored, it defaults to the value of CONFIG.Language (“enUS” by default).
Image Descriptions
magic_mush.png is a file in the mod/resources
local MOD = RegisterMod( “YAEID: Example”, 1 ) local function Register() YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM,”magic_mush.png”,nil,true} }) end YAEID_QUEUE = YAEID_QUEUE or {} YAEID_QUEUE[“yatboim_example_en”] = Register if YAEID ~= nil then Register() end
Modded Item Descriptions
Simply take advantage of the API function in the Isaac namespace:
integer GetItemIdByName (string itemName) integer GetTrinketIdByName (string trinketName) integer GetCardIdByName (string cardName) integer GetPillEffectByName (string pillEffect)
local MOD = RegisterMod( “YAEID: Example”, 1 ) local function Register() YAEID:RegisterCollectibles({ {Isaac.GetItemIdByName(“Marshmallow”), “A familiar that changes based on the last Fire Place it touched.n”.. “Extinguished by enemy projectiles and explosions.n”.. YAEID.COLORS.Grey..”Normal: Deals contact damage and blocks bulletsn”.. YAEID.COLORS.Orange..”Burning: Contact damage ignites enemiesn”.. YAEID.COLORS.Red..”Red Fire: Shoots flaming tearsn”.. YAEID.COLORS.LightBlue..”Blue Fire: Immune to projectilesn”.. YAEID.COLORS.Magenta..”Purple Fire: Shoots homing tears, immune to projectiles”} }) end YAEID_QUEUE = YAEID_QUEUE or {} YAEID_QUEUE[“yatboim_example_en”] = Register if YAEID ~= nil then Register() end
Language Support
You can create multiple entries for the same item for separate languages in one mod. Simply register another entry.
The code below sets the language override to nil. Any registration that omits its own language code will use the default language as defined in the main.lua. This is “enUS” by default, but a user could change it.
Then, three descriptions are registered for the Magic Mushroom item, one for the default “enUS”, one for Google Translated Spanish “spanishGT”, and one last fun one “joke”.
At the end, it sets the language override to “spanishGT”. The override will persist until it is changed again, so assuming this is the only yaEID mode to override the language, the player will see descriptions in “spanishGT” if they exist, their default language if it doesn’t, and if the default language has no descriptions, it will fallback to in-game descriptions.
local MOD = RegisterMod( “YAEID: Example”, 1 ) local function Register() YAEID_LANGUAGE_OVERRIDE = nil YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM,”A really good item, pick it up every time!”}, {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM,”Un articulo realmente bueno. !Recojala cada vez!”,”spanishGT”}, {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM,”I mean, it’s a mushroom. You probably shouldn’t eat it, but…”,”joke”} }) YAEID_LANGUAGE_OVERRIDE = “spanishGT” end YAEID_QUEUE = YAEID_QUEUE or {} YAEID_QUEUE[“yatboim_example_en”] = Register if YAEID ~= nil then Register() end
Language Support (with Fonts)
First and foremost keep in mind that the API DOES NOT READ font files from mod folders. so to get this working you (any people who download the mod) must place the font files into the resources folder at SteamSteamAppscommonThe Binding of Isaac Rebirthresourcesfont. If Nicalis ever fixes this, mods should not have to be updated.
There is support for hotswapping fonts in the middle of a description. First, register a font by path to get the font key:
local JAPANESE_FONT = YAEID:RegisterFont( “font/japanese/mplus_10r.fnt” )
Now, when you want to switch to the font that supports Japanese characters, just append JAPANESE_FONT to the string:
YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM, JAPANESE_FONT..”マギクマシルム”} })
You may want to have a custom language only for a specific portion of the code, so using YAEID.FONT in a string will set the font back to the user’s default:
local JAPANESE_FONT = YAEID:RegisterFont( “font/japanese/mplus_10r.fnt” ) local UNSET_FONT = YAEID.FONT YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM, JAPANESE_FONT..”マギクマシルム”..UNSET_FONT..” ( Magic Mushroom )”} })
Lastly, you should always make sure to use a specific language override to ensure that you don’t overwrite descriptions for the previous description packs language.
YAEID_LANGUAGE_OVERRIDE = “jp” — Registration Code
Putting this all together, here’s an example mod that uses the games default japanese font (mplus_10r.fnt) to add a simple Japanese translation to the Magic Mushroom item:
local MOD = RegisterMod( “YAEID: Japanese”, 1 ) local function Register() YAEID_LANGUAGE_OVERRIDE = “jp” local JAPANESE_FONT = YAEID:RegisterFont( “font/japanese/mplus_10r.fnt” ) local UNSET_FONT = YAEID.FONT YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM, JAPANESE_FONT..”マギクマシルム”..UNSET_FONT..” ( Magic Mushroom )”} }) end YAEID_QUEUE = YAEID_QUEUE or {} YAEID_QUEUE[“yatboim_japanese”] = Register if YAEID ~= nil then Register() end
Keep in mind that this sets the user’s language override to jp. If there aren’t definitions for other items in that language, it will fall back to the default language, and then to the game’s text.
Line Colours
If you use a particular character at the start of a line (the first character in the description or after any n character) you can set the colour of that line.
YAEID.COLOR_CHAR is a convenience table with names for these characters.
YAEID.COLORS = { White = COLOR..”FFFFFFFF”, ItemDescription = COLOR..”FFFFFFFF”, Black = COLOR..”000000FF”, Red = COLOR..”FF3333FF”, Green = COLOR..”33AA33FF”, Blue = COLOR..”3333FFFF”, Magenta = COLOR..”FF33FFFF”, Cyan = COLOR..”00DDDDFF”, Yellow = COLOR..”FFFF00FF”, DarkGrey = COLOR..”333333FF”, Grey = COLOR..”666666FF”, LightGrey = COLOR..”999999FF”, LighterGrey = COLOR..”BBBBBBFF”, ItemExtraInfo = COLOR..”BBBBBBBB”, ItemBaseDescription = COLOR..”666666FF”, LightRed = COLOR..”FF8888FF”, LightGreen = COLOR..”88FF88FF”, LightBlue = COLOR..”8888FFFF”, ItemTransformation = COLOR..”9999FFFF”, LightMagenta = COLOR..”FF99FFFF”, PaleCyan = COLOR..”33FFFFFF”, PaleYellow = COLOR..”FFFF99FF”, ItemName = COLOR..”FFFF99FF”, Orange = COLOR..”DDAA00FF”, ItemTag = COLOR..”DDAA00FF”, Pink = COLOR..”FFBBBBFF”, }
local MOD = RegisterMod( “YAEID: Example”, 1 ) local function Register() YAEID_LANGUAGE_OVERRIDE = nil YAEID:RegisterCollectibles({ {CollectibleType.COLLECTIBLE_MAGIC_MUSHROOM, YAEID.COLORS.White ..”Whiten”.. YAEID.COLORS.ItemDescription ..”ItemDescriptionn”.. YAEID.COLORS.Black ..”Blackn”.. YAEID.COLORS.Red ..”Redn”.. YAEID.COLORS.Green ..”Greenn”.. YAEID.COLORS.Blue ..”Bluen”.. YAEID.COLORS.Magenta ..”Magentan”.. YAEID.COLORS.Cyan ..”Cyann”.. YAEID.COLORS.Yellow ..”Yellown”.. YAEID.COLORS.DarkGrey ..”DarkGreyn”.. YAEID.COLORS.Grey ..”Greyn”.. YAEID.COLORS.LightGrey ..”LightGreyn”.. YAEID.COLORS.LighterGrey ..”LighterGreyn”.. YAEID.COLORS.ItemExtraInfo ..”ItemExtraInfon”.. YAEID.COLORS.ItemBaseDescription ..”ItemBaseDescriptionn”.. YAEID.COLORS.LightRed ..”LightRedn”.. YAEID.COLORS.LightGreen ..”LightGreenn”.. YAEID.COLORS.LightBlue ..”LightBluen”.. YAEID.COLORS.ItemTransformation ..”ItemTransformationn”.. YAEID.COLORS.LightMagenta ..”LightMagentan”.. YAEID.COLORS.PaleCyan ..”PaleCyann”.. YAEID.COLORS.PaleYellow ..”PaleYellown”.. YAEID.COLORS.ItemName ..”ItemNamen”.. YAEID.COLORS.Orange ..”Orangen”.. YAEID.COLORS.ItemTag ..”ItemTagn”.. YAEID.COLORS.Pink ..”Pinkn”} }) end YAEID_QUEUE = YAEID_QUEUE or {} YAEID_QUEUE[“yatboim_example_en”] = Register if YAEID ~= nil then Register() end
