See our [[Contributing Guidelines|Contributing to IITC‐CE]].


Quickstart
----------

To build the browser scripts from source you will need _Python 3.6+_.
It should build correctly on Linux and Windows (and, probably, _Macs_, _FreeBSD_, etc)

Fork this project, clone to your local machine.

Run the `build.py local` script to build the code.

If all goes well, output of the build will end up in `build/local` subfolder.

You can create a custom build settings file, `localbuildsettings.py` - look in the supplied
`buildsettings.py` for details.


Mobile
------

To build the mobile app, along with python, you will need:

- _Java JDK_ (development kit - the runtime _JRE_) is not enough).
  `JAVA_HOME` should be set (or 'java' command available in `PATH`).
- _Android SDK_.
  `ANDROID_HOME` should be set (or `sdk.dir` specified in `mobile/local.properties` file).

Run `build.py mobile` to build _IITC Mobile_ in debug mode.

More details in [[IITC Mobile (Android app)]].

Plugins
-------

Plugins may be developed in the same way as the total conversion script.
Plugins may provide features tailored to specific needs and are allowed to change things as they see fit.
You can provide them separately or submit a pull request to have them managed in this repository.
If you think a hook in the main script is required, simply open a bug report.

You can use the guess `player-level-guess` script as an example to get you started.
Just update the names and the code and you should be able to develop your plugin.
The outer wrapping code (seen in built plugin) ensures your plugin is executed after the main script.

If you happen the write general purpose functions for your plugin, consider adding them to the main script instead.
For example, if you write a `getResoCountFromPortal(details)` function it may be very well added to `code/portal_info.js`.


### Available Hooks

Available hooks are documented in the code.
Please refer to the [boilerplate explanation in `hooks.js`](../blob/master/core/code/hooks.js) to see which are available and how to listen for them. If you need additional hooks, open bug reports (preferably with patches attached).


### External Dependencies

If you have external dependencies put them into `external/` and add correspondent note into `versions.md` and `ATTRIBUTION.md`.


Details on Build System
---------------------------

Currently IITC-CE uses custom build system based on Python scripts (Python version 3.6+ required).

Execute `./build.py local` to effectively concatenate `main.js` with all the files in `code/`,
including resources from `images/` and `external/` directories.
It generates `build/*/total-conversion-build.user.js`, ready to be installed into your browser.

All source files in `plugins/` are processed in similar way, resulting in `build/*/plugins/*`.

**The files in `build/*/` are for release only and should not be touched manually.**

To change main script - modify the files in `code/`, to change plugin(s) - modify `plugins/*`,
then run build script to get all compiled.

`style.css` contains most styles required for the user-script. The extra ones can be found in `code/boot.js#window.setupStyles`.
Only CSS rules that depend on config variables should be defined there.
 
`external/*` is 3rd-party libraries, see `versions.md` for more info.