A reference on many useful or necessary functions for modding, as well as info.txt keyvalues.
Please note that this guide is incomplete and will be updated as I find more functions worth documenting.
This is not a guide on how to make mods!
Info.txt
## info.txt
info.txt follows the JSON structure. Here is a list of all the keys, they are mandatory unless otherwise specified.
Descriptions taken from sampleMod\main.js.
Type names written with (parenthesis) after them follow a specific formatting. i.e.:
String(id) => V - "some id" X - "Some-Id,Ï—"
Type names with [square brackets] after them indicate that it’s an Array of that type.
These two rules apply to the entire guide.
Name String
Example: “My Cool Mod”
The visibly displayed name of your mod.
ID String(id)
Example: “my cool mod”
The text id of your mod (alphanumeric characters and spaces only), used as its key when saving or loading data.
Also used as identifiers in other mods’ dependencies.
This id must be the same as the first parameter used in your Game.registerMod(id,hooks).
Author String
Example: “You!”
Your name here!
Description String
Example: “A mod that does cool stuff.”
A description of your mod.
ModVersion number
Example: 1
A number value for your mod’s version.
GameVersion number
Example: 2.031
The last version of Cookie Clicker this mod was confirmed to run on.
Date String(MM/DD/YYYY)
Example: “04/20/2069”
The date your mod was released or last updated.
Dependencies String(id)[]
Example: [“cool mod template”]
Optional.
An array of IDs of other mods that must be loaded before this one.
LanguagePacks String(filename)[]
Example: [“lang.js”]
Optional.
An array of local files containing localization data. (ie. changing game text, adding translations etc.)
Disabled number(0|1)
Example: 1
Optional.
If set to 1, this mod will be disabled by default.
AllowSteamAchievs number(0|1)
Example: 0
Optional.
By default, mods (unless they only consist of language files) block the unlocking of Steam achievements while enabled.
Set this to 1 if this is a good honest mod that does not incredibly unbalance the game.
Modding API
These were taken from the MODDING API section of the game’s main.js script.
Game.registerMod(id, mod) void
Call this function in your mod’s main.js file.
Mods and their data can be accessed with Game.mods[‘mod id’].
- id String – Your mod’s ID.
- mod object – The mod object. Must have these functions:
Â
Â
{ init: function() { // Called as soon as the mod is registered. Declare hooks here. }, save: function() { return 'save data'; // Use to store persistent data. }, load: function(str) { // Get the persistent data you stored with `save`. // str {String} - The data. } }
Game.registerHook(id, func) void
Register one or more hooks inder the specified hook ID.
- id String – The hook(s)’s ID.
- func function | function[] – What the hook(s) do. If you wish to later remove a hook, declare the function(s) somewhere else, then just reference it(them) here.
Game.removeHook(id, func) void
Remove a hook.
If you added the hook ‘my hook’ hook with Game.registerHook(‘my hook’, hookFunc), you’ll want to remove the hook with Game.removeHook(‘my hook’, hookFunc).
- id String – The hook(s)’s ID.
- func function – The hook.
Game.Loader.Replace(what, forWhat) void
Replace an existing canvas picture at runtime.
Args are filenames, i.e. /img/unCookie.png.
- what String
Â
The picture to be replaced. - forWhat String
Â
The picture what is replaced by.
Game.Notify(title, desc, pic, quick?, noLog?) void
Creates a notification at the bottom of the screen.
- title String
Â
The notification’s title. - desc String
Â
The description. Note that you can use HTML here.
Â
When using HTML elements that accepts JS in propertes, you may use ==CLOSETHIS()== to automatically close the notification when said JS is called.
Â
i.e. <a onclick=”Game.mods[‘my mod’].doStuff();==CLOSETHIS()==”>Do stuff</a> - pic number[] | String
Â
What icon to use. (Set to an empty String for no icon)
Â
Represents [x, y] coordinates on src/img/icons.png.
Â
For example, [2, 3] is the plain cookie icon. - quick? = 6 number
Â
Not reverse-engineered yet. Assumed it’s onscreen duration?
Â
Cannot be set to a value higher than `6`. - noLog? = false boolean
Â
Set to true to prevent logging of the notification.
Mod Hooks
Hooks are functions the game calls automatically in certain circumstances, like when calculating cookies per click or when redrawing the screen.
function customLogic() { // ... } // To add a hook Game.registerHook('logic', customLogic); Game.registerHook('logic', function() { // ... }); Game.registerHook('logic', () => { /* ... */ }); // To remove a hook Game.removeHook('logic', customLogic);
To add a hook, like logic, call Game.registerHook(‘logic’, function(){…}); in init.
To remove it, call Game.removeHook(‘logic’, theSameFunc);. (Note that theSameFunc must be the same function object!)
Function hooks are provided for convenience and more advanced mod functionality will probably involve manual code injection.
Please be mindful of the length of the data you save, as it does inflate the export-save-to-string feature.
NOTE: Modding API is susceptible to change and may not always function super-well.
Also, this guide is unofficial and may not be up-to-date!
logic:() void
Called every logic tick.
draw:() void
Called every draw tick.
reset:(hard) void
Called when the player resets a run.
- hard boolean
Â
Is true when the player hard resets instead of an ascension
reincarnate:() void
Called when the player has reincarnated after an ascension.
ticker:() String[]
Called when determining the news ticker text.
Return an Array of possible choices.
cps:(current) number
Called when determining the CpS.
Use to modify the CpS.
- current number
Â
The current CpS.
cookiesPerClick:(current) number
Called when determining the cookies per click.
Use to modify the cookies per click.
- current number
Â
The current cookies per click.
click:() void
Called when the big cookie is clicked.
create:() void
Called when the game declares all buildings, upgrades and achievments.
Use this to declare your own.
*Note that saving/loading functionality for custom content is not explicitly implemented and may be unpredictable and broken.*
check:() void
Called every few seconds when we check for upgrage/achievment unlock conditions.
You can also use this for other checks that you don’t need to happening every logic frame.
Helper Functions
Useful functions found in the MISC HELPER FUNCTIONS section of the game’s main.js script.
l(what) HtmlElement
Gets an HTML element by ID.
Shorthand for document.getElementById(what);
- what String
Â
The element’s ID.
choose(arr) Any
Returns a random element in an array.
- arr: any[]
Â
The array.
escapeRegExp(str) String
Escapes common characters used in Regular Expressions.
- str String
Â
The unescaped string.
replaceAll(find, replace, str) String
Returns str`, with all instances of `find` replaced with `replace.
- find String
Â
RegExp String. What to find. - replace String
Â
What to replace. - str String
Â
The String.
cap(str) String
Capitalizes the first letter of the String.
- str String
Â
The string.
romanize(num) String
Romanizes a number.
- num number
Â
The number.
Asset-Loading
This section documents the Loader function, responsible for asset loading.
Game.Loader.Load(assets) void
Loads an array of assets.
Not entirely sure if this is meant to be used by mods.
- assets String(url)[]
Â
The path of the assets to be loaded.
Game.Loader.Replace(old, newer) void
Replace an existing asset with a new one.
- old String(url)
Â
The asset to be replaced. - newer String(url)
Â
The asset that replaces old.
Other
Other functions.
AddEvent(html_element, event_name, event_function) void
Attaches an event to an HTML element.
- html_element HTMLElement
Â
The element to recieve the event. - event_name String
Â
The name of the event.
Â
It is recommended you name the event using kebab-case. - event_function function() => void
Â
What the element does when the event is fired.
FireEvent(el, etype) void
Fires an event attached to the element el.
- el HTMLElement
Â
The element. - eltype String
Â
The event to fire.
PlaySound(url, vol, pitchVar) void
Plays a sound.
- url String
Â
The url of the sound to play. (Will be cached so it only loads once) - vol? = 1 number
Â
Volume between 0 and 1. (Multiplied by game volume setting) - pitchVar? = 0.05 number
Â
Disabled!
Â
Pitch variance in browsers that support it. (Firefox only at the moment)
Â
Defaults to 0.05, which means pitch can be up to -5% or +5% anytime the sound plays.
PlayMusicSound(url, vol, pitchVar) void
Same as PlaySound(), but uses music volume instead of sound volume.
All args have the same purpose as PlaySound().
If you know a function that should be documented, please do comment!
(Preferably with the file name of the script and line number it’s in)
Hope you enjoy the Guide about Cookie Clicker – Functions for Mod API Reference + info.txt, if you think we should add extra information or forget something, please let us know via comment below, and we will do our best to fix or update as soon as possible!
- All Cookie Clicker Posts List
Leave a Reply