dark

Mod API Reference

admin
2021-09-08 13:16:05

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.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.

Use the dir property + the path to your image.

So if you have an image at the location <YourModDirectory>\MyImage.png, set this value to this.dir + "/MyImage.png".

(The this keyword in javascript is very confusing, so to simplyfy things, when you use it inside an object (but not a function inside that object), it references that object.)

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)

Changelog

09/07/2021

Added this changelog.

Removed duplicate definition of Game.Loader.Replace().

Added usage explanation to Game.Loader.Replace() -> newer argument.

Source: https://steamcommunity.com/sharedfiles/filedetails/?id=2592299023

More Cookie Clicker guilds

⮙