PIDEjL - Portable Intellivision Development Environment jzintv Launcher
PIDEGS - Portable Intellivision Development Environment Graphical Suite
Written by Michael Hayes
http://www.midnightblueinternational.com/pide.php
Date of last modification: March 24, 2023
__________

"What is this?"

This is a pair of graphical applications written in Python using Tkinter, one
of which allows you to select one of your Intellivision games and launch
jzintv, the other of which allows you to edit, compile & assemble, backup, and
playtest your Intellivision projects.  They use a point-and-click interface
rather than require you to type commands in a text window.  They are designed
for use with my Portable Intellivision Development Environment, the
documentation for which is available on my website listed above.
__________

What is included:

    readme.txt - what you are reading now
    pidejl.py  - the program to play Intellivision games
    pidegs.py  - the program to help you work on your own games
    config.py  - a configuration file that you can tweak
      play.sh  - the script to launch PIDEjL
      make.sh  - the script to launch PIDEGS
      temp.sh  - a script that is automatically generated and then executed
  includes.sh  - contains functions for launch.sh to draw lines and color text
   blueeye.png - application logo
   welcome.png - the dummy screenshot image that appears at start
  notfound.png - default image when a game is selected and no screenshot found
  hackfile.cfg - the default keyboard hack file for jzintv
   veckeys.cfg - an alternate keyboard hack file for use with Vectron
intycolors.cfg - an alternate Intellivision color scheme
  dbscript.txt - a script to automate the jzintv debugger when enabled
__________

Setup:

If you are using my Portable Intellivision Development Environment, then these
instructions are available at Step 10 of the documentation, but you can read
them here for your convenience.

A. If you are reading this, then by now you've already imported the .zip file
   and extracted it, creating the folder pidejl/ with all the files in it.
   The grom.bin, exec.bin, and ecs.bin files should be in your Home folder, as
   well as gromintv.bin and wbexec.bin if you have them.
B. Make sure the scripts and Python source files are executable, and create
   symbolic links, using the following commands (from the Home folder):
   chmod +x pidejl/*.sh
   chmod +x pidejl/*.py
   ln -s pidejl/play.sh play
   ln -s pidejl/make.sh make
C. Tweak the config file.  Open pidejl/config.py in your text editor.
     I. Do not delete any lines.  Just make changes as necessary.
    II. Change the paths as appropriate.
        a. Make sure there's a slash at the end of the path strings.
        b. We had copied jzintv to the Home folder, so the path shall remain
           an empty string.
   III. If you want to change the defaults of such things as the window size
        and border size, read the comment in the line just above each line.
    IV. The global options are parameters that will typically remain the same
        across all games.  They can be overridden by individual game
        parameters, such as the replacement keyboard hack file for Vectron.
        If you're trying to improve performance, try lowering the audiorate to
        11025 for starters.
     V. Updating the game list is the next thing to do here.  Make sure you
        read the directions in the comments just above before you proceed.
        a. The games will appear in the list in the order they are listed
           here: the list is not sorted alphabetically.
        b. The filenames of your ROM images are the next element.  You should
           already have updated the path to your ROM image files.
        c. Set the third option to 1 for ECS games or 0 otherwise.  When you
           select this game, the checkboxes will change appropriately.
        d. Ditto for IntelliVoice; use 1 if enabled or 0 otherwise.
        e. Next is a third number that is set to 0 for all the original games,
           since none of them used expanded GRAM.  New indie games might take
           advantage of double or quadruple GRAM, so if you add them to your
           GameList, change this number to 1 for double or 2 for quadruple.
        f. Any game-specific parameters you want to use will go into the sixth
           element.  This is ideal if you add games that use JLP.  In addition
           to overriding the keyboard hack file for Vectron, I also disabled
           speed throttling in USCF Chess, to give you another example.
    VI. Beneath the GameList is development-related stuff used by PIDEGS.
        Start by updating the paths if necessary, as well as the editor if
        you're not using geany.  Then it's time to update the ProjectList.
        a. First is the game title.  It will appear this way in the list, and
           also will become the title in the ROM header.
        b. Second is the subfolder within the projectpath.  Make sure there's
           a slash character at the end!
        c. There is another sublist for the third element, which is a list of
           all the source files to be edited or backed up.  If there is only
           one element, such as *.bas, leave a comma in the parentheses.
        d. The fourth element is the subfolder within the archivepath.  Again,
           don't forget the slash character at the end.
        e. Next, if your project uses JLP, enter "--jlp", or else use "".
        f. The sixth element is the main source file to compile.
        g. Finally, we have the base filename, which is used in a few places:
             i. The temporary assembler file
            ii. The debugger files
           iii. The box, overlay, manual, and screenshot images
            iv. The ROM image files: .bin and .cfg
   VII. Save and close.
__________

How to use:

Now it's time to try it out.  We'll start with PIDEjL.  Use the graphical
Terminal window.  From the Home folder, enter the command "play".

A window will appear with a list of games.  Use your pointing device
(preferably a mouse) to select a game in the list.

If you have a screenshot for that game, it will appear in the top left corner.
Otherwise, you will get a message to click the Play button.

The controls in the Peripheral Options frame will adjust themselves based on
whether the game is identified to support ECS and/or IntelliVoice.  In the
event you have a game that supports expanded GRAM, the controls in the Other
Options frame will change as well.

If you want to change the Graphics Options from their defaults, you may do so.
These do not change when you select another game.

Click on the Play button when ready.  It is greyed out until you have selected
a game.

If you have a box image for that game, it will appear in the background.  If
you have an instruction manual, it will appear in a window in the top-right
corner.  If you have an overlay image, it will appear in a window in the
top-left corner.  Then jzIntv will launch in the center.

When you're done playing, the overlay image and manual windows will disappear,
the box image will disappear, and the launcher window will reappear.

You can choose another game and play some more, or click on the Quit button.

For PIDEGS, type "make".  A similar window will appear with your project list.

In addition to the Play and Quit buttons, there are now buttons to Edit, Make,
and Backup.  There is also a checkbox for TutorVision.

The Edit button will open your editor with all of your specified project files.
Make will run IntyBASIC, and if there are no errors, it will run as1600; and
if there are still no errors, it will display the contents of your .cfg file,
and copy the ROM image to where your games are stored.  The Backup button will
back your source files up to the specified Archive folder.

As for the TutorVision checkbox, it will use gromintv.bin to replace the
standard grom.bin and wbexec.bin to replace the standard exec.bin when you
launch jzIntv.  It will also prompt you before disabling ECS (which is
incompatible with the TutorVision) and enabling Quadruple GRAM.  Unlike with
PIDEjL, there is no warning about enabling extra GRAM.
__________

License Stuff

There is no license or warranty of any kind.  Like the rest of the files I make
available on my website as part of my Portable Intellivision Development
Environment, I offer this package as a tool, and not as a product.  You are
free to do anything you want with these files.  The only disclaimer is that the
standard keyboard hackfile is something I downloaded from intellivision.us and
then modified for this environment.  That and the standard precaution that the
use of this environment, and any part of it, is at your own risk.  Do let me
know if anything needs to be fixed though.
__________

EOF
