Day 1: Ana­tomy of a Cus­tom The­ory

Guide writ­ten by prop. Con­tri­bu­tions from the Amaz­ing Com­munity.

Dawn of the first day. Last night, did you dream good?

Today we will be look­ing at an ex­ample of a cus­tom the­ory, in or­der to see how one can be con­struc­ted. We will send a the­ory through the SDK, then take a look at its source code.

Push­ing your first file #

Let’s first learn how to send a file to your device through the SDK. Open the SDK, and then click on The­ory Path to se­lect a file to send. Choose Cus­tom­The­ory.js right from the SDK’s root folder.

Now, con­nect your phone to the SDK. In or­der to do so, con­nect your work­ing en­vir­on­ment (com­puter with SDK) and your gam­ing device (phone) to the same net­work, and then you need to know the IP ad­dress of that mu­tual net­work. To do so, first enter your com­mand line in­ter­face:

• Win­dows: Right click the Start but­ton, se­lect Ter­minal.
• Linux: For Chrome­book users, fol­low this tu­torial. Oth­er­wise I think you’re nerdy enough to know this.
• Mac: Click the Launch­pad, search for Ter­minal.
• For Visual Stu­dio Code users, press Ctrl+Shift+` to bring up a ter­minal.

Your com­mand line in­ter­face has a com­mand to show con­nec­ted net­works:

• ip­con­fig for Win­dows & newer Linux ver­sions, or
• if­con­fig for Mac & Linux.

Find the afore­men­tioned mu­tual net­work, which may show up with a name sim­ilar to Wire­less LAN ad­apter Wi-Fi, and note the IPv4 ad­dress. If you’re us­ing an emu­lator such as Bluestacks, there may be a dif­fer­ent net­work that you need to con­nect to (in my case, it is called Eth­er­net ad­apter vEth­er­net (Bluestack­s­Nxt)). Note that the emu­lat­or’s IP ad­dress may change every time it is star­ted, or when your com­puter is re­booted.

In-game, ac­cess the cus­tom the­ory panel us­ing the bot­tom ar­rows, un­til you reach a screen say­ing Tap to se­lect a cus­tom the­ory. Enter the menu, press the SDK but­ton. Write the IPv4 ad­dress into your gam­ing device, while the ad­dress in the SDK can be left as Any, un­less you’re a mas­ochist.

Then tap Con­nect to SDK. The SDK will be­gin send­ing the first file to your phone, which will show up in-game as My Cus­tom The­ory. Try it out for a few minutes. Sub­sequently, whenever you edit and save that file in a code ed­itor, the SDK will re­send it auto­mat­ic­ally to the con­nec­ted device.

Suc­cess!

My Cus­tom The­ory #

Now, let’s dis­sect the file, sec­tion by sec­tion. If there’s any­thing you do not un­der­stand, feel free to skim through.

First, we see five lines of im­port state­ments. Re­mem­ber how yes­ter­day, I told you that mod­ules were not sup­por­ted by the game’s JavaS­cript in­ter­preter? This means that we will not be able to sep­ar­ate our the­ory into mul­tiple source files for easy keep­ing. So why im­port at all? The an­swer is, there is ac­tu­ally one in­cent­ive to keep im­port­ing the things you need from the cus­tom the­ory API: it is for the syn­tax high­light­ing and auto-com­ple­tion fea­tures of your ed­itor (if avail­able). Your ed­itor may even auto­mat­ic­ally im­port things for you.

Next is the in­form­a­tion sec­tion. Here we see four im­port­ant vari­ables: id, name, de­scrip­tion, and au­thors (as well as ver­sion and re­lease­Order, which are only used for of­fi­cially adding a the­ory into the game):

• id: The the­ory’s iden­ti­fier. Must be unique from other the­or­ies on the web. The game keeps track of the­or­ies’ IDs in or­der to store their data.
• name: The the­ory’s name.
• de­scrip­tion: A de­scrip­tion of what the the­ory is about.
• au­thors: The per­son/​people who made this the­ory.

These in­form­a­tions can be viewed by press­ing the cog but­ton in the the­ory se­lec­tion menu. As these vari­ables are ref­er­enced by the game out­side the the­ory’s scope, they must be de­clared with var, in­stead of let or const. The same is true for al­most all of the func­tions we will be dis­cuss­ing be­low.

De­clar­a­tions #

After a few other vari­able de­clar­a­tions, we see our first func­tion: init. While this is tech­nic­ally not a func­tion re­quired by the game (which means you can also use let or const for this), it is a bund­ling of man­dat­ory de­clar­a­tions: up­grades, per­man­ent up­grades, mile­stones, achieve­ments, and story chapters. init is called once at the end of the file.

This is the first place where we en­counter what’s known as an ar­row func­tion: var init = () => {…;}. They are men­tioned in Sec­tion 8 of the JavaS­cript tu­torial, and aside from a few dif­fer­ences, they’re mostly identical to nor­mal func­tions covered in Sec­tion 5. An ar­row func­tion’s ar­gu­ments are spe­cified in par­en­theses like nor­mal func­tions, while the func­tion body is writ­ten in­side the code block after the ar­row.

At the be­gin­ning of the func­tion’s body, we see a cur­rency be­ing defined us­ing the­ory.cre­ate­Cur­rency. The cur­rency takes the de­fault sym­bol of the Greek let­ter rho ($\rho$).

Then, within the Reg­u­lar Up­grade sec­tion, we see two up­grades, each de­clared in a code block: c1 ($c_1$) and c2 ($c_2$). They are de­clared us­ing the func­tion the­ory.cre­ateUp­grade.

Next, Per­man­ent Up­grades are defined. There are 3 func­tions provided to cre­ate up­grades for Pub­lic­a­tions, Buy All, and Auto-buyer, but you can also cre­ate your own per­man­ent up­grades us­ing the­ory.cre­ate­Per­man­en­t­Up­grade.

In the Mile­stone Up­grades sec­tion, the mile­stone cost is defined us­ing the­ory.set­Mile­stone­Cost, and then there are 2 mile­stones be­ing defined us­ing the­ory.cre­ateMile­stone­Up­grade: c1­Exp and c2­Exp.

Next, 2 Achieve­ments and 2 Story chapters are defined. They are, most of the time, pretty easy to set up com­pared to the up­grades and mile­stones.

Fi­nally, up­dateAvail­ab­il­ity is called. You can see that it is called be­fore it is ac­tu­ally defined be­low. This is a concept known as hoist­ing, covered in Sec­tion 17 of the JavaS­cript tu­torial. up­dateAvail­ab­il­ity is also a re­quired func­tion, as it is of­ten used to dis­play and hide up­grades de­pend­ing on play­er’s pro­gres­sion or other con­di­tions. It needs to be defined as a var so the game can ac­cess it within init.

Heart of the The­ory #

The next func­tion, tick, is where everything im­port­ant hap­pens. Terms get re­cal­cu­lated, cur­ren­cies in­crease, bins get re­packed, and re­act­ors scream. Ten times a second, this func­tion is called by the game, with two ar­gu­ments:

• elapsed­Time: elapsed time, in seconds. When in-game, it is most of­ten 0.1, and oc­ca­sion­ally 0.2 or more if the pro­cessing could­n’t catch up with the pre­vi­ous tick. When off­line, this ar­gu­ment can be of any value de­pend­ing on your off­line time and the off­line ac­cel but­ton.
• mul­ti­plier: usu­ally 1, this ar­gu­ment be­comes 1.5 when the ad boost is act­ive.

The LaTeX for­mu­lae #

The the­ory util­ises three for­mu­lae:

• The primary (up­per) equa­tion, through getPrimaryEqua­tion. It needs to be re­freshed manu­ally every time you want to re­flect a change (e.g. new mile­stone or term un­locked), us­ing the­ory.in­val­id­ateP­rimaryEqua­tion.
• The sec­ond­ary (middle) equa­tion, through get­Sec­ond­aryEqua­tion. It needs to be re­freshed manu­ally us­ing the­ory.in­val­id­ateSec­ond­aryEqua­tion.
• The pub­lic­a­tion for­mula, through get­Pub­lic­a­tion­Mul­ti­pli­er­For­mula.

When we look at the sec­ond­ary equa­tion or the pub­lic­a­tion for­mula, we can see that the func­tions don’t ac­tu­ally have a code block at­tached:

var getSecondaryEquation = () => theory.latexSymbol + "=\\max\\rho";
var getPublicationMultiplierFormula = (symbol) => "\\frac{ {" + symbol + "}^{0.164} }{3}";

In­stead, they ex­ist on only one line. This in­dic­ates that the func­tions im­me­di­ately re­turn the fol­low­ing ex­pres­sion, and this code is the short-hand equi­val­ent of:

var getSecondaryEquation = () =>
{
    return theory.latexSymbol + "=\\max\\rho";
}
var getPublicationMultiplierFormula = (symbol) =>
{
    return "\\frac{ {" + symbol + "}^{0.164} }{3}";
}

Also note that com­pared to reg­u­lar LaTeX, the LaTeX com­mands in-game must be star­ted with two back slashes, in­stead of one.

Pub­lic­a­tions #

The pub­lic­a­tion mul­ti­plier is de­term­ined by get­Pub­lic­a­tion­Mul­ti­plier, which takes the tau value (of the last pub­lic­a­tion) and re­turns the mul­ti­plier as a BigNum­ber - the game’s large num­ber (‘ee’ and up) lib­rary.

The tau value is de­term­ined by getTau, based on the cur­rency value. As a high-score met­ric, tau can only in­crease and never de­crease, un­less the the­ory is re­set.

Graph­ing #

The the­ory, like most, fea­tures a 2D graph dis­play­ing the cur­rency’s value on a log­ar­ithmic scale. The graph’s value is up­dated 10 times per second through get2D­Graph­Value.

The terms #

The last four func­tions are used to cal­cu­late the terms in the the­ory:

• getC1 cal­cu­lates $c_1$’s value as a step­wise power sum. An ex­plan­a­tion of step­wise power sums will be given later.
• getC2 cal­cu­lates $c_2$’s value as powers of two.
• getC1­Ex­po­nent cal­cu­late $c_1$’s ex­po­nent ac­cord­ing to the c1­Exp mile­stone.
• getC2­Ex­po­nent cal­cu­late $c_2$’s ex­po­nent ac­cord­ing to the c2­Exp mile­stone.

Af­ter­math #

Now that you’ve gone through the sample cus­tom the­ory, you now know roughly how one is struc­tured, even if it’s only a simple one. Per­haps your the­ory could in­volve even wilder ideas. I can’t dic­tate your thoughts, I can only give you the tools to help you do it. And the very first tool you were given: ob­ser­va­tion. I shall see you to­mor­row, where we will take part in your first cre­ation.