GGame tcl plugin

By Gary Arndt
(Refer to the "Credit" section, below, for other sources including the tcl language and source code, as well as some elements of Ultima II used in the test scenario)


********************************************************************************
Introduction
********************************************************************************

The core plugins manual is in the base plugins install package.  Before proceeding, refer to that manual.  These are additional, specific instructions for using the tcl plugin.

The tcl plugin allows any scenario in the game to connect to the 3rd party scripting language tcl.  Some scenarios may make use of this capability and therefore require it to be installed.  To do so, follow the instructions in the core plugins manual.  But basically, this means copy the plugins\tpi subdirectory from here to the plugins subdirectory of the game.

If you are a scenario designer, be aware that this plugin only supports a very specific, custom version of tcl that I modified very slightly then built (many years ago, well before this document was written); it is not possible to simply drop in or install some other version and expect for it to work.


********************************************************************************
Using this plugin
********************************************************************************

A player does not normally need to read this section; it is really intended for those who want to use a plugin in their scenario design.

The only time a player may want to try the following is if they are having trouble that could be related to this plugin and want to test that it is installed correctly as a troubleshooting step.

To test that the tcl plugin is installed correctly, follow these steps:
- First, follow the steps in the core plugins manual for using the plugin console
- Any of a huge variety of command are available since they consist of any built-in tcl commands and a few new custom tcl commands.  One command that can be used to confirm that the plugin is functioning is "tpiMessage TEST", which should result in the text "TEST" being displayed.

The core plugins manual describes how a scenario designer should reference the plugin.  But basically, this involves setting the scenario[ID].dat file PLUGIN setting to point to the main plugin file.  By default based on these instructions, that would be "plugins\tpi\plugin-tcl.dll", but as mentioned in the core plugin manual, it could be anywhere you want (although that means another scenario expecting it elsewhere could lead to complications).

In other words, it is likely to be:
PLUGIN: plugins\tpi\plugin-tcl.dll

This package also includes a generic initialization script and several example scripts that are part of an included example scenario.  The former is named "init-gpi.tcl" and is referenced by the example startup script named "tpi.tcl".  The former is located in the same directory as the plugin whereas the later is located within the DATA directory for the example scenario (in the "plugins" subdirectory, so at "DATA1\plugins").  To run a script such as tpi.tcl as a step in loading the plugin, use the PLUGINCMD setting described in the core plugins manual.  But if it is placed in the same location as it is for the example scenario, the setting would be as follows:

PLUGINCMD: tpiSource -DATADIR "plugins/tpi.tcl"

The purpose of using the "-DATADIR" option rather than simply something like "DATA1/plugins/tpi.tcl" is to avoid hardwiring the data ID in case it changes.

The example scripts are located within the DATA directory in order to encapsulate them since they are scenario-specific.  You may want to consider doing the same for your own scenario by copying the example scripts and making any modifications that you need.  You could still use tpi.tcl as the starting point and allow it to continue referencing init-gpi.tcl, but you will probably want to change the reference from test1.tcl to your own file.

The tcl language itself is beyond the scope of this document.  There are many online resources and books on the subject.

The tcl plugin adds several custom commands using tcl's TEA mechanism (tcl extended architecture).

Here are some important custom tcl commands implemented by the plugin:

tpiSource [[-DATADIR]] [filename]
(for example: tpiSource -DATADIR "plugins/tpi.tcl")
Works like the standard tcl "source" command but does some extra setup specific to the plugin.  The "-DATADIR" option will prepend that directory to the given filename in order to avoid hardwiring the DATA ID (this means that a relative path is required that begins with the data dir).

tpiMessage [[-nnl]] [string]
(for example: tpiMessage "This is a test")
Displays a message (more directly and therefore potentially more quickly than through another command like tpiSCMD).  The "-nnl" option means "no new line".  Refer to the core plugin manual for details ("API message").

tpiCMD [command] [[arg1] [... [argN]]]
(for example: tpiCMD RandomInt 1 10)
Runs the given standard API command.  Refer to the core plugin manual for details ("Standard API command").

tpiSCMD [script command] [[arg1] [... [argN]]]
(for example: tpiSCMD GiveItem 1 1)
Runs the given built-in scripting command.  Refer to the core plugin manual for details ("API script command access").

Normally, this plugin is used by calling a tcl command with the PICMD standard scripting command.  Refer to the core plugin manual for details.


********************************************************************************
The example scenario
********************************************************************************

This package includes an example scenario based on a small subset of the Ultima II demo scenario that has been heavily modified.

Note that a copy of the main game binaries is included in order to run this, but may not necessarily be as up-to-date as that in the main game install package so the scenarios subdirs should not be mixed between these separate installs (there are sometimes dependencies that change between the data and the binaries).

The details of starting and playing the game is beyond the scope of this document; refer to the main game manual for that information.

The purpose of this example scenario is entirely to provide a demonstration of how to implement the use of this plugin within a custom scenario.  Data files such as scenario[ID].dat and the tcl scripts are particularly useful to that end.

To play the example, start the game and enter the adjacent village.  The guard will tell you to talk to the wizard named Aticus.  The conversation with the later is written entirely using the plugin.  The other elements of the scenario are simply to support some of what he says and for color (note that some of these additional elements are also intended to be entertaining or interesting).


********************************************************************************
Credit
********************************************************************************

To be clear, I wrote the plugin entirely myself.

I also made some minor modifications to the 3rd party tcl source code and built the corresponding tcl binary myself.

The Tcl language and base source code itself is 3rd party software by "The Regents of the University of California" and free for redistribution.  Specific license details are available online.

This package includes an example scenario based on a small subset of the Ultima II demo scenario that has been heavily modified.  This package is a special supplement for the main game and the manual for the main game provides the detailed credit for other sources such as Ultima II; refer to that document for more information.

However, to be clear, Ultima II is a game by Richard Garriot of Origin Systems, Inc.

That said, I wrote all of the code for the game and almost all of the data myself except for the Ultima demo scenario's hand-translated tiles, maps, sounds, and some of the NPC text.  Again, refer to the main game manual for more details.
