====================================================================== - 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 ("" [,""] [,""] ) 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). is the name of the key configuration to use. is the name of an option to use. and , , ... 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 ). 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 () 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 - 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.