Boson Scripting Bible

$Id: scripting_bible.txt,v 1.9 2002/11/16 21:01:15 nikoj Exp $
$Date: 2002/11/16 21:01:15 $
$Revision: 1.9 $

Submitted by: Kal Kolberg
Written: November 8th, 2002
Copyright: Kal Kolberg (c) 2002 kolberg@cyberdawgs.com
License: GPL 2.0  http://www.gnu.org/copyleft/gpl.html

   This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; version 2.
   This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

   You should have received a copy of the GNU General Public License along with
this program; if not, write to:
 
The Free Software Foundation, Inc.
59 Temple Place
Suite 330,
Boston, MA 02111-1307, USA


==================================================================================

1) Introduction
1a) Contact information
1b) Purpose
1c) Philosophy
1d) Overview

2) Scripting Engine Design
2a) How the engine works
2b) How engine reads scripts
2c) Types of scripts acceptable

3) Scripting Triggers and Events

4) Strategic scripting

5) Tactical scripting

6) Unit scripting

7) Modifying AI for difficulty levels

8) Functions

9) Branching

10) Default Scripts

11) Bibliography:


==================================================================================
1) Introduction

This bible is an effort to create a useable scripting language for which in game
triggers and events will be written and a usable ai can be developed.

1a) Contact information

The website for the Boson project is:
http://boson.sourceforge.net

This documented is located in the CVS repository under code/boson/docs/scripting_engine

IRC Contacts for boson are irc.openprojects.net:6667  #boson

Beta copy of the scripting engine is to be ready by 5/23/03... ie my birthday

1b) Purpose
To provide a blueprint for the programmers of boson that will provide level
creators, ai programers and game designers the tools they need.

1c) Philosophy

My philosophy has developed through over 20 years of computer gaming starting in
1975 playing Star Trek on PDP mainframes to the current state of the art
graphic..

Very few games have captured the essence of what it takes to be a RTS Game.  Too
many have settled for trigger driven programming rather than actually produce a
generic system to handle events properly.

RTS Gamers tend to be highly intellegent computer savvy users and if they notice
a flaw in the ai or the system in general will exploit it to the point of
absurdity.  In order to combat this, the scripting/AI engine needs to be fast
flexible and to a certain degree self modifying...

This document entails numerous sources that I have collected and worked with
over the years.  Hopefully the final result will be something that will
challenge me even though I understand how it was built.

1d) Overview
The scripting engine will be the interface with the triggers, unit actions, and other scripting requirements... It will also work as the interface for the external AI system.

The reason for it pulling double duty is that it will be the de facto language that scripters and game designers will use and it doesn't make sense to duplicate a lot of functionality with different designs.   Thus we provide an integrated system that has the same syntax both of game scripting and AI scripting.

Triggers and Events vs AI Scripting
Triggers and events are static actions that the game takes depending on a set of
circumstances... In game actions, end game scenerios, etc are all functions that
must be run at specific times and cannot get pushed back because some other
script is running... As such triggers and events get priority scheduling also
not that the triggers and events can do pretty much anything in a game from
giving units and money to players, to taking them away, to determining a winner.

Tactical vs Strategic Scripting
Tactical scripting has to do with units that are available moving them around
etc...   Strategy on the other hand covers resource gathering, buildings and
unit production... It's influenced by the tactical engine, but is not the same
as... This is where the majority of AI will take place.

2) Scripting Engine Design
2a) How the engine works
The script engine itself runs the same whether it is behaving as the trigger scripting system or it's working as an AI system...   The only difference is that the trigger script has a higher access level and can send commands to the other ai's.   To implement level designer customer scripting.

Will have to build a scheduler and insure that each script gives up control to other scripts on an as needed basis.

AI's need to be limited to a certain number of actions per turn, each action has
a cost associated with it...  Therefore for an easy computer opponent may get 1
action every 3 seconds real time... Whereas an expert ai could get 10 actions a
second...   AI difficulty factor will be controlled by this...

Please note, that the cheat that most games do for their ai, giving extra
resources, etc is done through triggers thus you can have an easy computer
opponent with huge resources... whereas the expert system is probably going to
be able to use those resources quickly.  This allows players to go to a slightly
more difficult system, but to understand that they are losing because the
computer cheats and vice versa when they are losing to non-cheating computer
they understand that it's because they have a bad strategy.

Since the scripting engine is time oriented it will need to be given a game time
from the game engine...

One of the things that the engines should do for ai's is to connect through KGAMIO's so that player and ai's are handled the same.

2b) How engine reads scripts
Different scripts have different layouts... or xml tags... An AI personality
will have a number of xml tags, a tactical plan another set etc... Everything
will be read in and processed during the beginning of the game...

This also means that we have limited room for scripts since it must be stored
within system memory...  If we begin swapping out memory, this could be bad...
The game engine should tell the scripting engine how much memory it has
available and the scripting engine will work within the parameters passed by the
gaming engine.

Scripts should be able to be read both in text form and in a compiled form.

2c) Types of scripts acceptable
AI Personality
Tactical
Trigger Events
Special unit scripts

3) Scripting Triggers and Events
Real time processing... Several cycles each second spend in the trigger section
making sure that no trigger is triggered...

Root process for lack of a better term

Can set flags in the AI processes in order to change behavior, from a simple,
okay new unit type is available... To completely changing the personality of the
AI.

Text messages
Endgame and start game conditions


4) Strategic scripting
Building orders
Units and buildings
Should build units by both number and ratio
Resource gathering
Can allocate income for different projects...  And make determinations on
whether to keep saving or to spend
Should build pre-requisits if something is missing or lost from what it wants to
build.


5) Tactical scripting
Should be able to put units into groups so it can give the group orders rather
than individuals.

Track goals, shouldn't change goals every time the ai looks at a unit, but
should if there is need.

Able to request certain units from strategic script

AI limited to sight and memory just like the human player fog of war affects 
computer as well.

5a) Defense
AI will chose from multiple types of defense
Detecting attack
Protects most critical stuff first
responds to threats
determines units to send based on enemy unit types

5b) Offense
AI will chose from multiple types of offense
Coordination with other AI's
Will work to defend with other AI's
Unit positioning
detecting target
sends probes
determines units to send based on enemy unit types

6) Unit scripting
Scripts for units when they need to preform some action
Run picture script.. ie animation


7) Modifying AI for difficulty levels
Primarily done by the number of actions an ai can do per turn... Each action has
a value associated with it...

But you also have different AI types, attackers, defenders, rushers, squaters
etc.  So some scripting is done to handle different types.

8) Functions
List of all functions needed within the game

9) Branching
Conditional branching to make these programs a true programming language and not
just a script

10) Default Scripts
No idea what I want to put here yet

11) Bibliography:

Neural Networks in RTS AI
Author: Timothy Adam Smith Thesis paper.
Submitted: October 2001
University of Queensland
School of Computer Science and Electrical Engineering

Excerpts from email with Scott MacDonald <sctprog@sctprog.com>



