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

- Sim beta 1c for TI89/TI92+/V200 -
Copyright (c) 2003 by Olivier Armand (ExtendeD) - All rights reserved.

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

Please take the time to read the whole file (including the paragraph
'Important Notes') before using Sim.


What is Sim ?
==============

Sim can emulate programs created only for one calculator on the other
TI68k model (i.e. programs built only for TI89 can be run on
TI92+/V200 with Sim, and vice versa).
Sim can also be used to remap the keys of any program, when their
configuration does not suit you.

Different key configurations can be created and maintained easily
with a script typed in a text file in a straightforward format.

Only the keyboard emulation has been implemented for the moment, but
the screen emulation on TI89 should come soon.


Using Sim
==========

Sim must be run from the command line :
sim ("<program>" [,"<config>"] [,"<option1|option2|...>"] )

<program> is the path of the program to emulate. If the program is
 compressed (ExePacked), it MUST be the name of the PPG file, NOT
 the name of the launcher (the ASM file).
<config> is the name of the key configuration to use.
<optionX> is the name of an option to use.

<config> and <option1>, <option2>, ... are optional parameters :
"thiscalc" and/or "force (see below). If there are more than one
option, they must be separated with the caracter '|' ('with'),
without any spaces between them.

If the program you want to emulate accepts command line parameters,
add them after Sim's parameters (after Sim's options if they exists).
But you *must* specify the key configuration to use in that case.


The Script
===========

Sim needs a script to choose which keys to remap, and how to remap
them. This script must be a text file called 'simkscpt', created in
any folder, with the following format :

config_name1 : original_key1 -> new_key1, orignal_key2 -> new_key2,
  etc.
config_name2 : original_key1 -> new_key1, etc.
config_name3 : etc.

You can use the script provided in this package ('KeysScript.xxt')
to see how it looks like. It is important that you choose the file
for YOUR calculator.

You can create different key configuration, one for each program or
type of program. This allows you to choose the configuration you want
for the program to emulate, or for a program for your calc which keys
do not suit you.

The configuration name (for example "config_name3" for the example
above) must be used when running Sim (it's the parameter <config>).
The name is case sensitive. You can leave out this parameter : the
configuration 'default' will be used automatically (if found).
The 'simkscpt' sample provided in this package has only this
configuration. You can add other configurations to it if you want.

If you don't want to use any configuration, use "none" as the
configuration name : there will be no low-level emulation (see below :
'The keyboard emulation').

You can find other details on the syntax of the script, and the list
of the name of all the keys in the file "ScriptSyntax.txt" of this
package. You *need* to read this file if you want to create a new
configuration.


The keyboard emulation
=======================

First Sim read the script. Then it tries to remove the calculator
detection if there is one (that displays the message "Wrong calculator
model" when the program is run on the wrong calculator).

Then it applies several patches and installs different handlers for the
emulation of the keyboard. There are two emulations : the emulation of
ngetchx() and the low-level emulation.

The emulation of ngetchx() corrects the problem of the mixed arrows
when the AMS function 'ngetchx()' is used to read the keyboard. This
function is often used in the main menu of a game, when entering your
when name for a new high score, or when the program does not need
a fast scanning of the keyboard.
You can suppress this emulation by putting an underscore character
('_') before the name of the key configuration in the command line
(for example '_config'), but you should not need to use this option.

The low-level emulation is the emulation of TIGCClib's _rowread()
function, or any similar function to scan the keyboard.
The key configuration typed in the script 'simkscpt' only concerns
this emulation, not the ngetchx() emulation.
If you use 'none' as the name of the configuration, only the ngetchx()
emulation will be used.


Remapping the keyboard
=======================

When you are not emulating a program, if your simply want to change
the configuration for the keys of a program for the right calculator
(a program created for the calculator Sim is running onto), you
should use Sim as it you were emulating a program for the other calc,
but you MUST also tell to Sim that you are not emulating the program.

To do this, the third parameter of Sim (<options>) must be the string
"thiscalc". Note that you must specify the name of the keys
configuration to use if you are using one or more options (the
configuration 'default' cannot be selected automatically).

Note that the keys at the left of the STO character in the keys
configuration of the script must exist on the calculator Sim is
running onto when you use the option "thiscalc".


Forcing the keyboard emulation
===============================

Sometimes the low-level emulation may not work with some programs. In
that case, you can try to force the emulation by using Sim's option
"force".
For example : sim ("prgm", "default", "force")
Forcing the keyboard emulation might be slow down the execution of the
program, but it should work on any program that cannot be emulated in
normal mode.
If you find any program whose keyboard scanning cannot be emulated,
even in forced mode, please e-mail me (see 'Contacting the author').

You can combine the option "thiscalc" with the option "force", to
force a keyboard remapping :
   sim ("prgm", "default", "force|thiscalc")
where '|' is the caracter 'with' (2nd + K on TI92+/V200).

Note that the option "force" does not work correctly on any version
available of Virtual TI.


Important Notes
================

* The executables (sim.9xz, sim.89z) do NOT work on any  calculator :
  use the file with the correct extension (use the files .9xz on V200
  if there is no .v2z files).
  If you use the OS PedroM, use the executables sim_pedrom.xxz.
  If you use AMS, version 2.04 or higher is required. You can use
  nevertheless sim_pedrom.xxz but with a TSR or a kernel (such as
  PreOS) installing a Line 1111 Emulator for the ROM Calls.

* Try not to forget keys and avoid creating an invalid keyboard
  remapping in the script ! Else you may not be able to do anything in
  the program you are emulating, and you may not be able to return to
  the OS. You will have to reset the calculator.

* Do not forget the option "thiscalc" when running a program that
  works on your calc and does not need an emulation (when you just
  want to remap the keyboard). And do not use this option if the
  program needs an emulation. Else the key configuration will not be
  read correctly by Sim.

* Programs with parameters can be emulated by adding their parameters
  after Sim's parameters. Note that you *must* specify the
  configuration to use the configuration 'default' cannot be selected
  automatically).
  For example : sim ("prgm", "default", prgm_param1, prgm_param2)
           or : sim ("prgm", "mycfg", "thiscalc", prgm_param)


To Do
======

* Debug, improve and integrate to the project the screen emulation on
  TI89.


Disclaimer - License
=====================

I cannot be held responsible for any damages and/or data loss
resulting directly or indirectly from the use of Sim.

You are not allowed to re-distribute this package or any part of it
without my authorization.


About the source code
======================

The source code is included with the pack in the folder 'src'.
The source code is provided for your curiosity, and to let you help
me improve the program.
But please ask me before using any part of it in your programs.


Contacting the author
======================

Ask your questions about Sim, report the bugs, the problems when
 emulating some programs or any spelling mistake in this file to :
	Olivier Armand - <ola.e-ml@wanadoo.fr>


History
========

   06/18/2003 : Release beta 1c
                - Now compatible with PedroM.
                - "force" option added : most of the programs can now
                  be emulated without any problems.
                  Read 'Forcing the keyboard emulation'.

   04/20/2003 : Release beta 1b
                - Anti-self-emulation protection added.
                - A small bug in the routine reading the arguments
                  corrected.
                - Programs accepting command line parameters can now
                  be emulated.

   02/23/2003 :	Release beta 1
		First Public Release.


Thanks to :
============

* The TIGCC Team (http://tigcc.ticalc.org) for their great job.

* Thomas Nussbaumer (http://tict.ticalc.org) for his powerful ExePack
	compression/decompression tools.

* Kevin Kofler and Samuel Stearley for their advice and their bug
  reports.

