Smart City Plan mod API documentation



How to create a simple mod
Mod functions
How to debug your mod
API documentation


How to create a simple mod

If you don't know how to create very basic mods, you can take a look at the Creating mods section of the game manual. You can create basic mods even without programming. This document here is only for programmers.

Requisites: If you don't have this, you might want to take a look on how to create mods without programming instead.

To start:
  • Download the "Detailed City Report" mod. See using mods for how to do this.
  • In Windows, right-click the Windows start button in the task bar, and select 'Run'. There, type 
    %localappdata%
    and press ENTER. You should find a folder named "Smart City Plan" and under that, a folder named "mods". A folder named "detailed city report" should be in there, which contains the just downloaded "Detailed City Report" mod.
  • Copy the "detailed city report" folder and name it how you want your mod to be called, like "my mod".
  • Go into your new "my mod" folder and take a look at its content. You will find these files:
    • Open the script.js file and replace it with your own code, for example with this (which is a very simplified version of the detailed city report script): 
    new function()
{
	this.LastTimeRan = 0;	// last time this mod ran
																				
	this.run = function()    // <- called about ~30 times per second by the game
	{
		var now = game_get_time();
		if (now - this.LastTimeRan < 120) // only run every 120 minutes in game time
			return;

		this.LastTimeRan = now;

		game_send_mail('Population: ' + game_get_city().Population, 'hourly report');
	};
}

    This code will send a mail every two game hours to the player, with the current population amount of the city. Not very useful, but good as example code.

    It works like this: You need to define a function object, which has a method named 'run'. This is being called every game logic step. In there, you can do your game logic and access and manipulate the game.

    Mod functions

    When you create a mod, it can expose the following functions:

    run()

    This is called about 30 times per frame by the game. In this function, you can analyze the game state and manipulate it, how you feel like. But be sure that you don't do very heavy calculations every frame, otherwise the game will start running slower. A usual way is to limit the amount of the function to run to about once every game hour (that's about once every 3 seconds). To do this, do it like this: 
    new function()
{
	this.LastTimeRan = 0;	// last time this mod ran
																				
	this.run = function()    
	{
		var now = game_get_time();
		if (now - this.LastTimeRan < 60) // only run every 60 minutes in game time
			return;

		this.LastTimeRan = now;

		// do the things you actually want to do here 
	};
}

    deinit()

    This is optional and not needed. This is called when the mod is de-initialized. Like when the game is stopped, the mod is uninstalled, or when the mod is realoaded. You don't have to override this function, but it is useful in case you modify the internals of the game logic or the game data with your mod. In deinit(), you can undo your changes, so that the game runs nicely again.
    The following example shows this: It sets the unlock population value of the coal power plant to 0. When uninstalled, it restores the original default value again. 
    new function()
{
	this.Initialized = false;	// we only store if we ran already or not
																				
	this.run = function()    
	{
		// we only need to run once, in the beginning of the game
		if (this.Initialized) return; 
		this.Initialized = true;
		
		// we set the unlock population count of the coal mine to 0, so that it is unlocked at the start of the game.
		getBuildingTypeDataFromType(game_get_city().BT_POWER_PLANT_COAL).UnlockPopulationCount = 0;
	};
	
	this.deinit = function()
	{
		// this is called when the mod is deinitialized. set the default value back again.
		getBuildingTypeDataFromType(game_get_city().BT_POWER_PLANT_COAL).UnlockPopulationCount = 8600;
	}
}

    onCommand()

    This is optional and not needed. This is called when you create a mod which adds a button into the user interface, and that button is clicked. Download the "mark all mail as read" mod to see how this works, for example.
    To add a new button into the user interface (it will be added in the "Mod" tab in the building palette), add a section like this into your mod.json file: 
    "scriptCommandButtons":
[
	{
		"name": "Mark All Emails as Read",
		"id": "mark_emails_as_read",
		"icon" : "emailread.png"
	}
]
    And use code like this to react to the command, when it is clicked: 
    new function()
{																			
	this.run = function()    
	{
		// do nothing. This script is only for testing the mod commands
	};
	
	this.onCommand = function(cmd)
	{
		// a mod command button was pressed 
		
		if (cmd == 'mark_emails_as_read') // this is the id as specified for the button in the mod.json file
		{
			// now mark all mails as read
			game_runaction('markallasread'); // this is actually an undocumented feature in the game engine, but it works
		}
	}
}


    How to debug your mod


    Once you create a more serious mod, you probably want to be able to debug the mod, and be able to see the content of your variables. Smart City Plan contains a full debugger, complete with breakpoints and similar, as known from most web browsers.



    To use it, do it like this:
    In the top of your script, even outside of the run() method, store your 'this' variable in a global variable, like 'MyMod'. Also, call the function game_open_dev_console(). So that your code now looks like this: 
    new function()
{
	this.LastTimeRan = 0;	// last time this mod ran
	
	// out-comment the following two lines again if you don't need to debug it anymore
	MyMod = this;
	game_open_dev_console();
																				
	this.run = function()   
	{
		// ....
	};
}
    Then, when Smart City Plan loads your mod (for example when you click the 'update' button in the mod browser, or you start a new game), then it will open the debugger, like in the image shown above. In the 'Sources' tab, there is a "Watch Expressions" section. Into there, add a variable named like you named the global variable in your script, in our example, this is "MyMod". Then, expand that variable, so that the "run" function is visible and right click on its text "function", and select "Show function definition". There, you can now add breakpoints and other things, and debug your mod.

    Note: The game will likely run a lot slower when the debugger is active.

    API documentation


    Here is a list of most basic functions which are available to you:
    Note: Mods are not sandboxed. You are on your own, and you can break stuff easily in the game, so be careful. On the other hand, that way, you can do nearly everthing in the game.
    Some functions are a bit obfuscated and named for example "_irr43". Don't use these, they are really only for internal usage.

    City

    The 'city' object can be obtained using the global game_get_city() function. It returns the city with a lot of functions and properties. Some of them are listed here:

    Properties

    Methods



    BuildingInstanceData

    The building instance data represents one building in the city. They are stored in the city.Buildings[] array. Some of their methods are listed here:

    Properties

    Methods



    BuildingTypeData

    The building type data represents the type of a building instance. It can be obtained using the buildingInstance.getBuildingTypeData() function, or the global getBuildingTypeDataFromType(type) function.

    Properties

    Methods