OpenTTDDevBlackBook/IConsole/Scripting

From OpenTTD
Jump to: navigation, search
External Links

OpenTTD GitHub
Contributing to OpenTTD - guidelines
OpenTTD Doxygen

General Reference

Coding style
Compiling OpenTTD
Debugging
Add a setting
Add a squirrel function
Understanding the SaveGame handler
Bumping the savegame version
Doing an OpenTTD release

Language and Strings

Format of langfiles
Using OpenTTD strings
List of special strings

Window System

Using the window system
Colour codes that exist in OpenTTD
Adding a text box
Understanding the widget focus system
GUI style guide

Multiplayer

The OpenTTD TCP protocol
The OpenTTD UDP protocol
Debugging desyncs
Server Admin Port development

Ingame Console

The console window
Console commands
Console variables
Using console scripting
Adding functions/commands to the console
Adding variables to the console
Console development history

Content APIs (modding frameworks)

Graphics and similar (NewGRF)
AI framework (NoAI)
GameScript framework (NoGO)

Other Reference

Map array (landscape grid)
Vehicles
Pathfinding
Train acceleration


This document explains how to use console scripting.

If you want to test the scripts below you must have compiled with DEBUG=1.

Contents

Commands

Commands [also called Functions] are used to give the scripter the ability to access some specific aspect of the OpenTTD sourcecode. Currently there are only some basic commands implemented. Therefore we currently only have some access to OpenTTD Functions.

]screenshot

This command causes OpenTTD to make a screenshot of the current screen. It is immidiately executed and does not return a result.

]random
result = 41

This command causes the system to generate a random number. It is immidiately executed and returns a result. If the result isn't assigned to a variable, it gets dumped to the console. If you want to add commands to the console read HOWTO - Add Functions/Commands to the Console

Variables

Variables are used to

  • Access OpenTTD defined C Variables
  • Store information which is used by your script

The scripting language can handle the following types of Variables:

  • BOOLEAN [direct memory access]
  • BYTE [direct memory access]
  • UINT16 [direct memory access]
  • INT16 [direct memory access]
  • UINT32 [direct memory access]
  • INT32 [direct memory access]
  • POINTER [direct memory access]
  • STRING [instance based]

Direct memory access? Instance based? Uhm?
Direct memory access means that the variable's memory position is fixed. This gives you the ability to change OpenTTD owned variables directly from the console. Instance based means that if the variable gets changed from the console it gets a new memory address which is pointing to newly allocated memory space. The old memory space is freed only if the variable is only used by the console. So if you add an OpenTTD byte * variable to the console and you try to change its content.. you won't change the string used by OpenTTD but you will change the variable in the console.

Below, variable names are indicated by a "*"

]*temp_uint16
*temp_uint16 = 0
]*temp_uint16 ++
*temp_uint16 = 1
]*temp_uint16 --
*temp_uint16 = 0
]*temp_uint16 = 32
*temp_uint16 = 32

Most of the variable types have the ability to perform different actions:

function description
 ++ increments the value
 -- decrements the value
 = assigns another value [dont try to use this to copy the value of one variable to another variable]

If you want to know how to add variables to the console, read HOWTO - Add Variables to the Console

Functions [Commands with return values]

In some cases, it is neccessary to:

  • copy the value a command returns
  • pass a variable pointer to a command [implemented in console rev 3]
  • copy the value of one variable to another [implemented in console rev 3]

copy the value a command returns

]*temp_uint16 << random
*temp_uint16 = 41

But:

]*temp_uint32 << random
ERROR: variable type missmatch

You'll get this error if the returned value of the command does not have the same type as the variable does. A well coded function [random is no example for this :D] could do a trick to detect what type of variable it has to return. [token shifting] Read HOWTO - Add Functions/Commands to the Console

passing a variable pointer to a command

]varinfo @*temp_uint16

copy the value of one variable to another

*temp_uint16 << *temp_uint16_2
Personal tools