{
 "title": "Creating mods",
 "slug": "creating-mods",
 "category": "Mods",
 "url": "https://x-change.life/wiki/creating-mods/",
 "summary": "Introduction",
 "tags": [],
 "checked": null,
 "game_version": "0.27.0.9",
 "words": 3113,
 "headings": [],
 "links": [],
 "watches": [],
 "markdown": "Introduction\n\nX-Change Life™ is written in Harlowe, a Twine “Story Format”. Twinery is no longer used for development, the project has been fully decompiled using Tweego, into human-readable text files (thanks to the patient efforts of togashikokujin). These text files use the .twee file format and are readable using a text editor.\n\nThis method of doing things also allows user-created content to be created for the game, using the [mod loader](https://gitgud.io/xchange-life/mod-loader).\n\nTools\n\nThe first step to doing anything behind the scenes is to be able to read those files. You may use whichever text editor you prefer, but it is highly recommended to use Visual Studio Code (commonly referred to as VS Code, or VSC) You can download and install VS Code (from [https://code.visualstudio.com](https://code.visualstudio.com)). Once installed, you should also download and install the [twee 3 language tools](https://marketplace.visualstudio.com/items?itemName=cyrusfirheir.twee3-language-tools) extension from the extensions tab (in the left panel.)\n\nGame Repository\n\nWhen you go to play the game, you are running a compiled HTML file. If you go to try to open that compiled file, you will be overwhelmed with terrible formatting and an endless wall of text. The core game files themselves are actually separated out and organized neatly into sections. We look at these smaller, more digestible files, when we want to reference the game code. You can view the game’s files on the [gitgut repository](https://gitgud.io/xchange-life/xchange-life/-/tree/main).\n\nThere is a search feature, where you search for files or the code inside of the files, to be able to find certain things. This is a nice way to quickly spot check information in a pinch, but the best way to work with these files is to clone into the repository and download a local copy of all these files onto your computer. By doing so, you’ll be able to perform global searches inside of VS Code, which makes references these files and the code inside much easier than having to visit a website and search around.\n\nYou can clone the repo manually through command line ([instructions here](https://github.com/git-guides/git-clone)) or you can use repository management software (such as [GitHub desktop](https://desktop.github.com/download/)) to do it for you.\n\nOpening Game Files\n\nI highly recommend setting up a workspace in VS Code specifically for XCL. When you do, you can select to add a folder to that workspace. Go ahead and add the game’s repository to the workspace. When you clone into it, you will have specified a location to put those downloaded files. This will be the folder that gets added. You can add additional folders as you develop your mod(s).\n\nNow that you have your workspace and your folder, go ahead and open one of the files so we can start to understand how the game is constructed.\n\n![](old/2025-01-image-1024x626.png)\n\nYour window should look something like this. If the text colors are off, then you need to find the Language Mode at the bottom right of your screen and switch it from “twee3” to “twee3-harlowe-3”.\n\nIf you look at the code you will see that it is divided into chunks called passages that all start with “`:: `“.\n\nYou can learn more about Harlowe (and I really encourage you to do so) by visiting: [https://twine2.neocities.org/](https://twine2.neocities.org/)\n\nThe `:: bar intro` passage is pretty simple in terms of what is happening.\n\nTwirl is a custom macro created for use in the game, it closely mimics what ([either:](https://twine2.neocities.org/#macro_either)) does, essentially it picks a random entry from the provided entries. So ONE of those lines will be displayed when `bar intro` is called. That is the first part of this passage.\n\nThe next is (display:”bar current patrons”). [Display](https://twine2.neocities.org/#macro_display) is a macro native to Harlowe, it essentially tries to write out the contents of the provided passage string. You can think of it like calling a function, in other languages like python. So this step would essentially just run the “bar current patrons” passage, which you could go look up if you wanted to continue down the path of figuring out what does what.\n\nThe last portion of this passage is a passage_tag. This is a little more of an advanced concept, but essentially what a passage_tag does is allow for inserting INTO this passage at that location, when the passage_tag is used. (Don’t worry if that doesn’t make sense, more on this later).\n\nWhat can mods do?\n\nAt the most basic, a mod changes what happens when a passage is run. If it adds new passages to run, those passages have to be somehow called, usually by modifying an existing passage. You can have very simple mods that change something minimal, very complex mods that change entire aspects of the game, or anywhere in between.\n\nHow to get started?\n\nOne of the best ways to get started is to look at an existing mod and walk through it to see what it does. Between looking at mods and looking at the base game, some things should start to click for you. A good first attempt at a mod could be something in the game that you wish would happen differently, or something you’d like to change.\n\nAltering Game Passages\n\nThere are three ways to alter a game passage with a mod. Some are more appropriate than others.\n\n1. Advising a passage (recommended) 😊\n2. Using passage tags (if available and fits your criteria) 👍\n3. Overwriting a passage (should only use when absolutely necessary) 😭\n\nAdvising a passage (using around)\n\nThe mod loader contains a feature for mods: *Aspect-oriented programming* (AOP). If you are a programmer you may already be familiar with this. The basic idea is that a mod can define *advice* that “modifies” a passage that already exists in the game, without having to overwrite that passage. Say for example the game contains the following passage:\n\n```\n<!-- Base game -->\n:: chicken\nWhy did the chicken cross the road?\n```\n\nNow we want to create a mod to add the answer. Previously, we would have to copy the entire passage, which overwrites it:\n\n```\n<!-- old-mod.twee -->\n:: chicken\nWhy did the chicken cross the road?\nTo get to the other side!\n```\n\nThis has two problems: It can be annoying to update when a new game version releases, and it can lead to conflicts with other mods that modify the same passage. Instead, we can define an *around advice* (the only type of advice supported at the moment) to modify the passage:\n\n```\n<!-- new-mod.twee -->\n:: chicken [around]\n(display:_around)\nTo get to the other side!\n```\n\nWith the mod loaded, when the “chicken” passage is displayed, it’s the modded passage that is displayed. The mod passage then in turn uses `(display:_around)` to display the original passage, before adding its own text. In effect, the mod has “modified” the original passage and appended its own text.\n\n`(display:_around)` can be used in more complex scenarios too. For example, a mod could only show the original passage conditionally:\n\n```\n:: chicken [around]\n(if:$animal is \"chicken\")[(display:_around)]\n(else:)[Why did the $animal cross the road?]\n```\n\nWhen applying advice, the mod loader will produce the following code internally from the base game and new-mod.twee samples given above:\n\n```\n:: chicken-answer\nWhy did the chicken cross the road?\n\n:: chicken\n(set:_around to \"chicken-answer\")\n(display:_around)\nTo get to the other side!\n```\n\nMultiple mods can apply advice to the same passage without issue. `(display:_around)` in one mod’s advice will display the advice of the second mod, and the second advice’s `(display:_around)` will then call the original passage.\n\nModders can use this technique to modify some passages less intrusively, without copying. This should make it easier to update mods to new versions of the base game, and can improve compatibility between mods.\n\nPassage Tags\n\nPassage tags are listed and explained here:\n\n[https://gitgud.io/xchange-life/xchange-life/-/blob/main/project/twee/10-systems/utility/passage%20tags.twee?ref_type=heads](https://gitgud.io/xchange-life/xchange-life/-/blob/main/project/twee/10-systems/utility/passage%20tags.twee?ref_type=heads)\n\nAmong other things, passage tags are a way to handle mods being in conflict with each other.\n\nInstead of needing to overwrite the original game passages to change things at certain points, the game itself checks to see if it should do something else when it encounters these `$passage_tags`.\n\nModders can use these `$passage_tags` to insert new pieces of code into the original passage at the point that these tags are referenced.\n\nIf you refer to the image from earlier, it had `($passage_tags:\"bar_intro\")` at the bottom of the passage. This means we could create a passage and tag it with `[bar_intro]` after the name and have our code inserted at this specific point in the original passage.\n\nThe game looks for these tags when it encounters that call, if it finds one then it inserts the code from that tag and proceeds with the rest of that passage.\n\nYou would tag your passage like this:\n\n```\n:: my bar intro [bar_intro]                                                                                                                                                                         As the bartender speaks, a glass shatters in the backroom\n```\n\nThis would insert that line after the bartender’s introduction.\n\nRefer to the passage tags file for a full list and much better explanation of what each tag does.\n\nOverwriting Passages\n\nIf it can be avoided at all, overwriting passages should be considered a last resort. This is the fastest way to cause a mod conflict.  \nA conflict occurs when more than one mod tries to change the same passage. So, for example, if your mod and somebody elses both overwrite the `bar_intro` passage then the two mods would be in conflict.\n\nA basic first mod example\n\nLet’s try to make a mod with passage tags.\n\nOne of the things that you might want to be able to do at the bar would be speak to the bartender. This would mean that we want to add an option to the bar options passage. There is a passage tag there already so we can make a mod that won’t conflict with any others.\n\nSo the first thing to do would be to create a new file. Call it BartenderMod.twee\n\nThen we can start making the mod. First we need a name for the passage.\n\nLet’s call it\n\n`:: bartender chat        `\n\nRemember all passages start with “:: “\n\nNext, because we want it to go in as a bar option we need to attach the bar options passage tag. This tells the game to look at this passage when it reaches the part of the game where it gets to the bar options passage. So far the game will look at the passage but it’s empty so it won’t do anything. What we want is for it to do something.\n\nWe will type in:\n\n```\n:: bartender chat [bar_options](link:\"Chat with the bartender\")[($cs:\"bartender chat 2\")]\n```\n\nNow we are telling the game to do something when it looks about for passage tags and sees our tagged passage. We have told the computer to make and display a “link” (a link is a clickable button) and to call it “Chat with the bartender”. The $cs macro (short for “change screen”) means that screen will be changed to display whatever is in quotes, in this case it is the “bartender chat 2” passage.\n\nWe don’t yet have a “bartender chat 2” passage so we need to make one now. Type in:\n\n```\n:: bartender chat 2\nYou chat inconsequentially with the bartender until he has to go and attend to other customers.\n```\n\nNow that our passage was displayed, we need to get back to the main game somehow. So add this:\n\n`(link:\"Finish\")[($cs: to \"bar options\")]`\n\nAnd that is your first mod complete. It should look like this:\n\n```\n:: bartender chat [bar_options](link:\"Chat with the bartender\")[($cs:\"bartender chat 2\")]\n:: bartender chat 2\nYou chat inconsequentially with the bartender until he has to go and attend to other customers.\n(link:\"Finish\")[($cs: \"Hit the bar\")]\n```\n\nNow we want to add the mod to the game. Open the mod loader and click “Add Mods”. Browse to where you created the BartenderMod.twee file and select it. Now click “Load Mods.”\n\nNow you can play the modded game and test your mod. Head over to the bar and see if your new bar option appears!\n\nScreen Management\n\nIt should be noted that there are several methods of changing the screen, you may hear referred to as “change screen” or “next”, and a few others. Ultimately the methods you choose depend on your scenario.\n\nIn order to understand what method you need, you have to understand how the screen is laid out.\n\nCertain areas of the screen are commonly defined and redefined using Hook names. There are actually a lot of them, but let’s focus on just a few to begin with.\n\n![](old/2025-01-Screen-1024x576.jpg)\n\nThe hook referred to as “Screen” means the center column, where the majority of the story takes place.\n\n![](old/2025-01-Status-1024x576.jpg)\n\n“Status” refers to the left column, which houses your character’s portrait and stats.\n\n![](old/2025-01-Right-Screen-1024x576.jpg)\n\n“Right Screen” refers to the right column, which serves multiple purposes, such as showing your location, date, inventory, day planner, outfit portrait, and can show NPC portraits and info.\n\nThere are other hook names inside these, but these are three main areas. It’s important to know this, because the method of changing screens impacts these areas, and you may end up with blank screens if you use the wrong method.\n\nChange Screen\n\nThe change screen method ($cs) only replaces the center column, while leaving the other two intact. It exists in the code base in several different ways.\n\nThere is a passage called `:: change screen` , which was the original method of doing this. You would set $next to the passage name that you wanted to display, then you would display change screen.\n\nIt looked like this:\n\n```\n(set:$next to \"passage name\")(display:\"change screen\")\n```\n\nA macro was later created to shorten this, it should now be used like this:\n\n```\n($cs:\"passage name\")\n```\n\nThis differs from simply using (display:”passage name”), which would only run the code in that passage, without replacing any screen portions.\n\nNext\n\nThe next method ($nx) replaces the entire screen, all three columns.\n\n```\n<!-- Original Method -->\n(set:$next to \"passage name\")(display:\"next\")\n\n<!-- New Macro Method (use this one) -->\n($nx:\"passage name\")\n```\n\nThis is normally used when changing locations. Location intro passages are typically “fullscreen” and will set up all three columns, so you call them with $nx to clear out anything already there.\n\nSimple Option\n\n`$simple_option` is a macro that was created to help with scenes. It’s designed to offer you three methods of changing the screen, while providing a simple $choice variable that corresponds with what button the player clicked on.\n\n```\n($simple_option:\"passage name\",\"choice 1\",\"choice 2\",\"choice 3\")\n<!-- You can use any number of choices if you want (including only 1) -->\n```\n\nThe default method it uses to change the screen is the Change Screen method. Alternatively, if you include the word “display” or the word “next” (in all lowercase) you can instead force the macro to use (display:”passage name”) or ($nx:”passage name”), for display or next.\n\n```\n<!-- a display example -->\n($simple_option:\"buy more pills\",\"display\",\"buy 5\",\"buy 10\")\n\n<!-- a next example -->\n($simple_option:\"Go home and watch porn\",\"next\",\"Run home and watch porn\",\"Call a cab\")\n```\n\nUsing Hook Names\n\nHook names are generally set up like this:\n\n```\n[(display:\"character status\")]<status|\n<div id='scrollable-content'  class='center_screen' data-simplebar>[\n    []<image|\n    []<text|\n    <div class=\"options\">[]<options|</div>\n]<screen|</div>\n<div class='top_right' data-simplebar>[(display:\"location and time\")]<right_screen|</div>\n```\n\nYou’ll often see the [(replace:)](https://twine2.neocities.org/#macro_replace) macro used in conjunction with the hook name, in order to replace certain parts of the screen. Such as:\n\n```\n(replace:?text)[Some text here]\n```\n\nThis gets used a lot to change options, text, images, any named hook can be changed with this method. This is why sometimes you might see links (buttons) that will replace certain parts of the screen, but not change the entire screen.\n\nOther Helpful Tips\n\nLook at existing code or mods – they will give you an idea of what can be done and how to do it.\n\nIf you are looking at mods you may come across the .xcl file type. As noted above, .xcl files are re-named .zip files. These are used to try to make using the mod loader easier. The mod loader uses zipped up .zip files. A lot of people were unzipping the zip files and then the mod loader was not loading those mods properly. To prevent this there is now the option to re-name .zip files as .xcl files so that they can be used by the mod loader but people (hopefully) won’t unzip them. If you want to look at a mod in .xcl format you can just unzip it using any zip utility (because it’s actually just a .zip file with a different name). If you are having problems it may help to rename the file .zip instead of .xcl\n\nIf you are trying to do anything with audio it is a good idea to check the game settings in relation to audio – there are three settings – if you limit what the game plays then it will be very difficult to test your mod. I would recommend choosing the play all sounds option, at least when testing your mod.\n\nIn relation to audio, the $sex_loop variable will usually re-set to “0” when the passage changes. If you want it to continue in the next passage then you can set the variable $sex_loop_continue to “true”. If you are doing this, remember that you will need to stop the $sex_loop at some point.\n\nIt is important to realize that passage tags can be used in a range of circumstances for a number of different effects. Before changing parts of the base game you should look at the list of passage tags and see if you can use one of them.\n\nWhen playing the game use the ``` key to open up a special window – you can use it to set variables and check their values. This can be useful if you want to see how the game works in particular parts or ensure that your mod is working the way that it should be. Also, when playing the game use the 1 key to open up debug mode.\n\nWhen looking at the code you will see a lot of (text)[text]. The bit in the () is called a macro and the bit in the [] is called a hook. It may be helpful to think of them as (condition)[action]\n\n{} are special brackets to do with collapsing extra spaces (“whitespace”). They improve code readability without sacrificing in-game screen space\n\nSimilarly, Harlowe does not require the same sort of line and spacing discipline that features in other programming languages, for example, RenPy.\n\nSearching the discord channel can sometimes provide answers.\n\nAt the moment undefined variables default to “0”. So this means if you tell the game to check $apples and you haven’t already told it what value $apples is the game will use the value “0”.\n\nWhen you make a mod (beyond what is in this guide) we would appreciate if you shared it. There is a mod releases channel on the Discord where people typically announce their mods – though access to that channel is restricted so you will need to ask someone for permission to post there. Almost all mods are now hosted on Lovers Lab (https://www.loverslab.com/ specifically https://www.loverslab.com/files/category/319-x-change-life/). After announcing your mod I would suggest that you go there to upload your mod.\n\nFinally, if there is anything that you think is missing from this guide or that you found useful or helpful that is not mentioned please let us know so we can improve this guide (messaging us on Discord is probably best).\n\nMetadata\n\nBy default mods are loaded in alphabetical order and if they overwrite the same passage the mod loader displays a message indicating that fact. You can use metadata in mods to control their interactions with each other.\n\nInformation about metadata can be found here:\n\n[https://gitgud.io/xchange-life/mod-loader/-/blob/main/metadata_info.md](https://gitgud.io/xchange-life/mod-loader/-/blob/main/metadata_info.md)\n\nHelpful guides to help get started modding\n\nBe sure to check out the other articles for modding for more information how getting started.\n\n[https://x-change.life/wiki/docs-category/mods/](/wiki/special/all/#mods)\n\nAudio\n\nThe game uses the mp3 format, exclusively.\n\nAphrodite created a custom audio system, which I know nothing about (sorry)\n\nThe game used to uses the Harlowe Audio Library. Information about that can be found here:\n\n[https://twinelab.net/harlowe-audio/#/](https://twinelab.net/harlowe-audio/#/)\n\nUseful Links\n\n[VS Code](https://code.visualstudio.com)\n\n[Harlowe Manual (Refer to the manual!)](https://twine2.neocities.org/)\n\n[Harlow Audio Library](https://twinelab.net/harlowe-audio/#/)\n\n[Passage Tags](https://gitgud.io/xchange-life/xchange-life/-/blob/main/project/twee/core/utility/passage%20tags.twee)\n\n[LoversLab](https://www.loverslab.com/files/category/319-x-change-life/)\n\n[Unofficial Modding Tools](https://x-change.life/modding/tools.html) – Currently for Bar Girls, Player Characters, & Metadata.\n\nSpecial thanks to previous contributors of this article and everybody that helps out in the #mod-chat discord channel\n",
 "meta": {
  "title": "Creating mods",
  "category": "Mods",
  "imported": true,
  "old_modified": "2026-07-06",
  "old_urls": [
   "/wiki/docs/creating-mods/"
  ]
 }
}