Creating an Icon Mod (for Newbies)

1. Preamble & Basic Setup

First things first, some information: This guide assumes that you, at the very least, understand the basics of how the Basic Sample Mod is structured and how variables work in JavaScript.

This guide will contain some sprite advice, but it is NOT end-all art advice. Admittedly, we are not particularly fancy artists ourselves, and make no claim to be. The actual artistic should just be general advice to get your started so your mods don't clash with others.

This will not cover changing every graphic in the game, just icons. While most other images have a similar principle to them, some of them (for example, most clickables) do not, and that is beyond the scope of this guide.

In addition, to set up your mod from the basic Sample Mod "template": Remember to change the ID of the mod (both in info.txt and in main.js, under the first line's Game.registerMod call) to something unique!

Ensure that your info.txt contains the line "AllowSteamAchievs": 1 at the end of it, that the line before it ends in a comma, and that the AllowSteamAchievs line does NOT. Yes, it's picky, but this allows for Steam Achievements to be enabled with your mod enabled.

2. Spritework

Full disclosure: not an artist! Mostly an image editor. But we happen to know a few things you must follow for your mod to work, as well as a few tips to make it look actually decent.

Active requirements: Individual sprites must be 48x48. Icons in this game are exactly 48x48 pixels in size.

Your spritesheet must be in a dimension that's some multiple of 48 in both horizontal and vertical. It can be any matchup of multiples of 48, such as 144x96, but the width and height of your canvas should be cleanly divisible by 48. (Naturally, a canvas of exactly 48x48 works as well if you are only changing one sprite.)

Once you are done, save your spritesheet as a PNG inside the same directory as your mod. If it's a single icon, it should be 48x48 in canvas size. If it's a sheet of sprites, the width and heights should both be multiples of 48 to some capacity. For the sake of this guide, we'll pretend you saved it as sampleImage.png, but you may change the name as long as you remember to change the code accordingly (and honestly, we recommend you do exactly that.)

As for tips on making it look nice: This is extremely important if you want a mod that won't clash with others visually. Unless you're planning on making an HD texture pack, the effective icon size is 24x24; you then upscale this x2 (Nearest Neighbor) manually. You can save quite a bit of time in the artistic process by working with 24x24 icons and upscaling them late when actually inserting them into your spritesheet. (Of course, if you are deliberately planning on making an HD texture pack mod, you can ignore this...)

Cookie Clicker has a very specific color palette used across its icons. This much is fairly documented on the Discord, but if you're not a part of it (or otherwise don't want to rummage through it), you're in luck; simply color-pick from the game's vanilla icons.png file and you'll basically have the same color palette.

This should go without saying, but study the sprites of the vanilla game if you want a "feel" for how they should look. The "limited" palette often masks itself by using colors that, while seemingly unrelated at a glance, meld together to create a cohesive palette. (This is best exemplified with basically any "purple" icon, which often uses shades of cyan, blue, pink, and even light yellow as compliments.

Just avoid pillow-shading. In general.

3. ACTUALLY CODING: Initializing The Graphics

Now it's time to actually get to coding for real. At the start of the mod's actual function, you're going to want to declare a variable specifying your spritesheet you're going to be using. While you could repeatedly use the same line over this variable method, it saves space and makes the mod much easier to read and troubleshoot if something goes wrong.

For example:var custImg = this.dir + "/sampleImage.png";

In this example, the variable is known as "custImg". This will be the shorthand definition for the spritesheet "sampleImage.png", which is in the same directory as our mod. Rather than spamming this.dir + the filename operations over and over, this allows for a clean, compact, and readable way to declare the image.

If you chose to save your spritesheet as something not "sampleImage.png" (which we recommend you do), be sure to change up the line of code from the example.

4. (Optional) Mod Loading Notification

It's entirely optional if you choose to add this to your mod, but in the event you need to either debug if your mod is loading or to simply goof off, this is a nice inclusion. If not, feel free to simply ignore the following code.

An example:Game.Notify(`Mod loaded!`, `Some funny description goes here.`, [0, 0, custImg],10,1); The first string (distinguished by the first pair of ` symbols) is the notification's header.

The second string (distinguished by the second pair of ` symbols) is the notification's description.

[0, 0, custImg] refers to the top leftmost icon of the spritesheet you specified in Step 3. (If you want a different icon from the spritesheet, look at how to specify which icon in Step 5. If you want a vanilla icon, do that but also replace custimg with icons.png.)

The following ,10,1 ensures the notification stays open for 10 seconds before it automatically dismisses itself for the sake of the player.

5. Specifying Your Icon

It's extremely important that you understand how Cookie Clicker defines icons at all in making a mod. Luckily, the format is not particularly JavaScript-heavy for a user wanting to specify which icon they want.

This code is not an example in of itself, but it serves as a great demonstration of what specifying an icon is like:


To break it down: X,Y are, well, the X and Y coordinates of which icon you are specifying. By default, they start at 0; if X,Y are 0,0, it chooses the top-leftmost sprite in your sheet. (If you have only one sprite in your sheet, 0,0 is the only coordinate you need, as your only icon is at 0,0.) 0 is included as a number in this! If you want the icon 2 icons to the right of your top-leftmost icon, this would be [2,0,]

custImg is your variable you set in Step 3. This is short-hand for your custom spritesheet. Optionally, however, if you are changing an icon to an icon in the vanilla icons.png file, you may swap it for icons.png instead.If that was difficult to understand, don't worry. If you want to find what X/Y you should use for your icon quickly, but don't understand the coordinate system very well yet, simply take the pixel position of the sprite you want and divide it by 48. Implying you properly configured your spritesheet and every icon is 48x48, the result will be the icon you want.

Examples [0,0,custImg] = Top-leftmost icon of your custom spritesheet

[5,4,custImg] = The icon positioned at 240,192 on your custom spritesheet

[0,0,icon.png] = Top-leftmost icon of the vanilla spritesheet (e.g. the Tier 1 Cursor icon)

6. Actually Changing The Icons

Changing an icon requires you to have the name of the target achievement or upgrade, specifically sourced from the game's primary main.js file. Usually, you can easily locate these in-game, but some achievement names are a bit more complex, and may require a look in there with Ctrl+F to find what you want.

These names are case and formatting sensitive, and getting them wrong may either cause the mod to abruptly stop changing icons or even cause a total crash of the game until repaired or disabling mods! When in doubt, copy-paste the main.js name, add in a forward slash `\` in front of any seemingly problematic punctuation, and if changing multiple icons, comment out lines with // and try to narrow down the problematic one.

Upgrade example:Game.Upgrades['Reinforced index finger'].icon = [0, 0, custImg];This code changes the specified upgrade (the first upgrade to cursors) to the top-leftmost icon of our spritesheet (see Step 5 for notation). To properly specify an upgrade, you need to use Game.Upgrades; this includes both standard upgrades, heavenly upgrades, and cookie upgrades.

Achievement example:Game.Achievements['Click'].icon = [0, 0, custImg];This code changes the specified achievement (the first achievement for cursors) to the top-leftmost icon of our spritesheet (see Step 5 for notation). To properly specify an upgrade, you need to use Game.Achievements; this includes both standard and shadow achievements. Unsurprisingly, it's very similar in format to the upgrade one.

7. Main.js Source Code & Conclusion

If you just want a basic source code for your mod's main.js to work with, here you go. If you get stuck, there's a whole 6 chapters to read in case of that.

Game.registerMod("iconTemplateMod", { init: function() { // remember to change iconTemplateMod to your unique mod ID! // basic template code by Camwoodstock & Tori! <3 // creating custImg variable var custImg = this.dir + "/sampleImage.png"; // notification! Game.Notify(`Mod loaded!`, `Some funny description goes here.`, [0, 0, custImg],10,1); // changing icons Game.Upgrades['Reinforced index finger'].icon = [0, 0, custImg]; Game.Achievements['Click'].icon = [0, 0, custImg]; } });Regardless of your JavaScript experience, whether you're a total newbie with no coding experience at all, someone with some coding knowledge but no specifics on JavaScript, or you're a total JavaScript fiend, we hope this helped you at least a tiny bit with understanding changing icons, what makes them tick, and how to make them look at least a little better.

While more advanced topics such as mod compatibility/priority were not touched upon, those felt a bit out-of-scope for this basic guide. When in doubt, ask on the Dashnet Discord.

Now go, and do your best/worst/best!


More Cookie Clicker guilds