Introduction

Thank you for your interest in Project TI-Trek, the first massively-multiplayer online game for the Texas Instruments TI-84+ CE graphing calculator. This project has been a long time coming, and seen a lot of ups and downs, pauses and restarts, start overs, and many painstaking hours of figuring out what I did so wrong that my calculator achieved nuclear fusion while attempting to test it. I owe a debt of gratitude to fellow members of the calculator programming community, particularly Cemetech, whose encouragement and assistance has made this project possible. In particular, I owe an even larger debt of gratitude to a smaller subset of the community who have been actively involved in the development of this project, who will be named later in this document. And last but not least, I would like to acknowledge the inspiration from the genre of space-based sci-fi including Star Trek, Star Wars, Orville, Stargate, and others; My love of this genre was a major factor driving this project.

This project is one of, if not the first of its kind. It is an MMO, in which you can create and customize a virtual spaceship styled after the ones in Star Trek and its spinoffs. The game is set within a randomly generated map, with bodies that move through the sky, stars that experience their life cycle, and more. Not only is the map custom and fluid (although based on a set of pre-computed paths), but we also implement some aspects of real-world physics. Distances mirror those in real space, gravity is accurate, the sizes of objects are accurate. Gravity will affect all non-static entities, and of course stars and black holes and other celestial objects will pose a threat to players in the game, as well as other players.

Dependencies and Installation

As is to be expected, this is a highly complicated project, and it has a number of dependencies, without which it will not work properly. On the end user's side, this project requires that you install the Client program (TITREK.8xp) on your TI-84+ CE graphing calculator and that you download and extract (or git clone) the bridge onto your computer. The bridge performs the translation from serial traffic to TCP traffic and as such without it, you will be unable to actually play the game. You may obtain both pieces of software from the Downloads Page. You will also require an installation of python3, as well as the python module(s) pyserial on your computer in order to use the bridge.

In addition, this project also requires that you have present on your calculator several of the C libraries offered by MateoConLechuga: FILEIOC, GRAPHX, KEYPADC, USBDRVCE, SRLDRVCE. These can be installed by following the procedure outlined here. In order to actually build them, you will need the llvm compiler, with ez80 backend on your computer, which you can download here. In lieu of that, you can always poke around on Cemetech or the project's Discord server for a pre-built one. These libraries offer, in sequence: file interfacing, graphics and sprite manipulation, keypad interfacing, USB drivers, and Serial Device drivers. If you have used CE programs before, chances are you already have most of these.

The final thing you will need on your calculator is the assets pack for the UI. This is a collection of sprites that controls the basic look of your screen while you are actually playing the game... from the interior of your ship, to the iconized design of your ship, to the icons for ship systems, status, and more. The default one is available on the Downloads Page. Ensure that you download the correct graphics pack version for your Client version. If you choose to design your own UI assets pack, please follow the procedure outlined here. Please bear in mind that if you choose to design your own and they are similar to copyrighted assets from certain sci-fi tropes, distributing them may not be the best idea. Also please note that importing a custom assets pack will have no effect on the appearance of map objects and other player's ships, which are controlled by the server and... wait for it... other players.

Bridge Setup and Usage

Dependencies

The Bridge is a Python script written to allow the TI-84+ CE graphing calculator running the USB Serial library to connect to the Internet. Once you have the requisite software and dependencies, using the Bridge is fairly easy.

First, you will need to make sure you have a working installation of python3. Python versions before 3 will NOT work. If you do not already have python3 installed, you can install it by running apt-get install python3 python3-pip, or a similar command on whatever operating software your computer is running. "python3-pip" installs Python's module installer, which makes it easier to add libraries and modules to Python.

Once you've gotten that set up, next you will need to grab the dependencies. For now, the only one is pyserial, a module that adds methods for interfacing with serial devices (like the calculator). If you don't already have it, you can install it using pip3 install pyserial or pip install pyserial...which of the two commands you use depends on how your system installed and aliased python3-pip.

Configuration

The bridge comes with a configuration file, called config.json. This file contains some default settings for the bridge. I'll briefly explain them below:

port
Default port on which to attempt TCP connection. This can be overriden by Client (see Server List)
debug
Determines whether or not the bridge should print detailed packet relay information to the Terminal. Can be true or false.
mode
Determines whether the bridge is seeking an open pipe or an open serial device. Pipes are used for CEmu, serial device for a physical calculator. Can be pipe, cemu, default, or serial.
pipe files (pipe_in, pipe_out)
Paths to files that will be used in Pipe mode to communicate with CEmu. These are ignored for serial mode.

Usage - Pipe Mode

To run the bridge, simply type in Terminal python3 bridge.py, from the directory where the bridge files are located.

            Running in debug mode.
            Out pipe: /tmp/cemu-tocalc
            In pipe: /tmp/cemu-fromcalc

Once you see this, you are ready to launch CEmu (for maximum stability, run CEmu once to initialize the Pipes, then close it again. Also, this requires the USB branch of CEmu by commandblockguy.). Let CEmu open. Run the Client program on CEmu. As it initializes the serial device, the following will show up underneath the existing lines:

            Pipes opened
            ^C to exit.
            Serial listening.

If you see these lines AND ONLY THESE LINES, then you are ready to go. Simply play the game, and everything should work nicely. However, sometimes it may not go so smoothly. As the bridge can be a bit finnicky still, it may bug out, especially if CEmu had still written data to the pipes from the last instance. If the bridge is attempting to send packets at this point, simply exit out of the Client program completely, then close CEmu. This will trigger an exception on the bridge. That's what you want. Start the bridge again and things should be fixed.

Usage - Serial Mode

If you are running in Serial mode, the process is pretty much the same, but the procedure varies slightly. Start the bridge like before, to ensure everything will work properly. When you do so, you should see the following in Terminal.

            Running in debug mode.
            No device detected.

Now plug your TI-84+ CE graphing calculator into your computer. Start the Client program (see Client Setup and Usage for instructions if needed). You should be on the Splash screen (see below) and the USB indicator should be green (if it is red, see the Troubleshooting section). Now run the bridge again. You should see the following:

            Running in debug mode.
            ^C to exit.
            Serial listening.

If you do not see the above lines, again see the Troubleshooting section. If you do, congratulations. You are now ready to play the game.

Client Setup and Usage

Splash Screen

The first thing you will see whenever you run this program is the Splash Screen. This is your gateway to all the features of the program. You will see a screenshot of the splash screen to the right. The screen will consist of 2 main parts, a menu and some indicators. First, the indicators: At the very bottom of the screen you will see a USB indicator. This icon will be green to indicate that the serial interface is successfully set up and will be red to indicate that the serial device failed to initialize. Just above that, is the graphics error indicator, a text error that appears when the version of the graphics you have installed on your calculator is incompatible with the current program version. If you do not see this alert, you can rest assured your graphics are properly loaded.

Program Settings

Running the program for the first time will initialize a settings queue with default options for some of the key functions of the program. This will occur again whenever the settings save file is missing, or its size does not match that of the built settings queue. This also means that program updates that change the size of the queue will cause your settings to be reset. You can see the editable settings in the image to the left.

There are a few aspects of your gameplay experience that can be altered from the Settings page, accessed by hovering the selector bar over the Settings menu option and pressing Enter. In order, they are:

Debug Mode
Causes internal program debug messages to be displayed in the log widget
Prefer SSL
A currently unimplemented setting that causes the bridge to always prefer an SSL connection to a server, if able
Save Login Info
Saves your username and password so you don't have to keep re-typing them
Frame Refresh Rate
A combination of Entity and Chunk refresh rate, specifies how many ticks should pass between requests for new framedata
Packet Limit
A maximum number of packets to process each tick
Network Timeout Limit
A time period of inactivity that triggers a server ping; the server failing to respond to that ping causes the client to assume the network is down and exit the game
Log Display Length
How long individual log-lines stay on screen before they disappear

Server List

Selecting the Play Game option from the main menu brings up the server list, which allows you to choose from a selection of servers to connect to. Any valid form of server identification is acceptable here; hostname or IP address. You may also choose to add an optional port number using the :port notation. For example play.titrek.us or play.titrek.us:51701 are both valid. In subsequent releases, the entire hostname and port string would be prepended with a "s:" to open an SSL connection (eg: s:play.titrek.us:51701 or s:play.titrek.us). This is not necessary if the "Prefer SSL" setting is enabled. The default server, play.titrek.us, is filled in to the first slot by default and cannot be edited or removed; However, the other nine (9) slots may be filled with whatever server hostname, IP, and port you choose. As indicated to the right of the interface, the Enter key selects a server, and the Del key Edits (or Deletes) an existing server (to remove, simply press Enter without entering text when prompted for the server name).

Keybindings

Here is the list of default key associations for different actions within the game, starting with the main menu, server list, and settings menus, and then moving into the gameplay.

Main Menu
KEYACTION
navigate menu up
navigate menu down
Enterselect option
Clearquit game (same as selecting Exit)
Settings Menu
KEYACTION
navigate settings up
navigate settings down
toggle or decrease setting value
toggle or increase setting value
Enterselect option
Clearexit and save settings


Gameplay Keybindings
KEYACTIONKEYACTION
Y=enable/disable sensors interfaceWindowenable/disable tactical systems interface
Zoomenable/disable main systems interfaceTraceenable/disable repair system interface
Graphenable/disable ship inventory interfaceEnterselect module, tbd
Clearexit secondary menu, disconnect from server2ndfire armed weapon module
scroll through modules, steer ship downsteer ship left
scroll through modules, steer ship upsteer ship right

Gameplay

This game is a highly complicated and feature-rich game, and as such the interface is quite hefty. That being said, it does have a few key elements that you can see when you look at it. The biggest area of the screen is the "Viewscreen". It is a black window-looking area of the screen where the majority of the visuals and information you will see in this game are shown. The second main part of the screen is the "Overview Tabs". This section of the screen provides five basic informational categories that can be used to view more information about your ship. From left to right: Sensors, Tactical, Mains, Repair, and Cargo. Also, with none of the menu options selected, you can see an unobstructed view of space in front of you.

Main Systems Overview

This data screen shows abridged information about the main systems on your ship--those systems that control the basic functions of your ship. This includes engines--orbital thrusters, sublight engines, and FTL engines--as well as life support, transportation, sensors and more. On this screen, you will see: (1) A small icon representing the type of module, (2) A health bar indicating the current health of the module [this health bar will change color to indicate health danger zones], (3) And the overall background color of the module will change to indicate if the module is online or offline [green indicating online, red indicating offline].

Tactical Systems Overview

This data screen shows abridged information about the tactical (combat) systems on your ship. Much like the main system interface, these module backgrounds will change color to indicate online/offline state. Typically, only one weapon module can be "online" at a time, although that status will be referred to as "armed". Off to the left part of the screen, you will see some information about your overall ship status: (1) Two icons, showing the current design of your ship as seen from the side and top, with circles around them indicating shield integrity. (2) Under that you will see the current hull integrity, represented as a gray bar. (2) Underneath that, you will see a blue bar indicating overall shield stability (which is a cumulative health among all your active shield modules) if you have one or more shields installed. If you are in battle, you will likely want to spend a lot of time on this screen to monitor the status of your defensive and offensive systems.

Troubleshooting

Having a problem with one of the parts of this project? Chances are we encountered some of the same issues during testing already. Before you resign yourself to failure, have a gander at this list of issues we encountered, and suggestions to resolve them based on how we fixed it. Some of the information here might help you out.

Bridge Fails to Detect Physical Calc
  1. Is your calculator's USB port malfunctioning?
  2. Is your SRLDRVCE and USBDRVCE up to date?
  3. Is your settings savefile outdated? This can cause problems.
    Delete the appvar TREKSETT and try again.
  4. Is your computer running Windows? The serial/usb drivers don't play well with Windows. Wait for a fix.
Bridge Fails to Detect CEmu Pipes
  1. This is a known issue with CEmu support. The best solution at present is to keep starting CEmu, running the Client program, then quiting and closing CEmu with the bridge running until it detects the pipe files. After that, follow the directions for using the bridge normally.

Technical Info

In this section we will review some under-the-hood information about this game, including memory requirements, file creation, and more. It should go without saying that this game requires a lot of memory to run.

Files Used or Created

PGRM: TITREK
The Client Program
File Size: 20840 bytes
* You will need enough RAM free to accomodate the listed size.
APPVAR: TrekGFX
Default Assets Pack
File Size: 29930 bytes
*This remains in archive, and so RAM space is not needed.
APPVAR: TrekSett
Settings Save File
File Size: 585 bytes
* This is moved to RAM when saving settings, so listed size in RAM is needed.

RAM Areas Used

pixelShadow
userMem
Stack
Serial Buffer: 2048 bytes
Server-Side Assets Cache: variable
Splash Screen sprite: 13818 bytes
USB status sprites: ~750 bytes
Log indicator sprites: ~400 bytes
Game State saves: ~650 bytes
Assorted RAM for functions: ~1000 bytes

Credits

I would like to thank the following individuals for their significant contributions to this project:

Client-Side Programming
(Lead) Anthony Cagliano
Adam "beck" Beckingham
commandblockguy
Server-Side Programming
(Lead) Adam "beck" Beckingham
commandblockguy
Anthony Cagliano
Bridge Programming
commandblockguy
Sprite Designers
Bailey Conrad
Ampersand
Pieman
TurquoiseDrag0n

Legal Notices

Disclaimer

At long last we have arrived at the fun section -- the part where I turn into an alarmist and spend way too long freaking you out over worst-case usage scenarios that will likely never happen, but that I need to in order to cover arbitrary legal grounds.

This is a compiled C program, which means that on your calculator it is effectively assembly and is thus capable of breaking in quite spectacular and oftentimes amusing ways. For instance, how cool would it be to have your own personal firework-emitter, flamethrower, or nuclear reactor in your pocket, accessible by simply running our program. Unfortunately, however, should the FBI come calling, we will be forced to disavow all knowledge.

Dark humor aside, all official releases of this project are relatively stable, or stable enough that we can guarantee they will NOT trigger a nuclear meltdown of your calculator's circuitry. However, do be aware that improper usage of this software (in a manner inconsistent with the procedures laid out in this document) may cause some adverse effects. This includes but is not limited to: RAM clears, program and appvar corruption, and memory corruption. While we at Project TI-Trek have taken great care to ensure that all components of this project are stable, by using this software you assume any and all risk associated with it and agree to save harmless Project TI-Trek and its affilates.

Software Licenses

General EULA for Project Components

All major components of this project--server, client, and bridge--are the property of Project TI-Trek and of their respective developer(s) and are under intellectual copyright as laid out in Section 102 of the Copyright Act of 1976. The software components of this project are all distributed under the terms of the GNU General Public License Agreement v3 (GPLv3), and we assert that any distribution of our software must provide the same license agreement.

By common consent, we also assert that any assets, sprites, artwork, or publications released by us are also the property of Project TI-Trek and their respective designers or creators and that they are also distributed under the terms of GPLv3, with the same requirement that all subsequent redistributions/alterations be governed by the same license agreement.

The default game server provided by us for initial testing, and later sustainable gameplay, is governed by the same license as indicated in the first paragraph (GPLv3). However, be advised that the data files retained by our instance of the server are not. They are closed source, and viewable only by the individual account-holder to which they belong and, in abridged format, by Project staff on the Admin page of the "Web Deck". Be aware that gaining access to files on our server that you should not have access to is data theft, a cyber crime, and will result in prompt legal action.

EULA for Our Hosted Server Instance

As an end user of Project TI-Trek, you are given the privilege of using our server to play the game. In the initial stages, this server is used as a deployment environment to test new feature additions. However, it is also available for sustainable gameplay for project users. We will provide the ability to use our server free-of-charge for the foreseeable future. This means that not only is having an account and playing the game free of charge, but you will also not be asked to buy any special packages to unlock additional features or get more currency, access special areas of the map, or any of the other pay-to-win garbage that has become commonplace on almost every other MMO.

This being said, let me reiterate--the use of our server is a privilege, not a right. We can and will terminate your ability to use our service for violating our Terms of Service. The Terms are quite simple: don't be an asshole. If you are unclear as to what constitutes being an asshole, you probably need to re-evaluate yourself. But in the event you need a more specific breakdown, read on.

Modified Clients: Do not connect to our service with modified clients. We cannot guarantee that the server will support them, and we do not know what kind of advantage using it will give you over other players. Don't do it. It will get you IP banned.

Online Conduct: We expect a level of maturity from users. The server will at some point support a global chat. This means it will likely come with its share of trolls and flamers. Let's have no pretense here: trolling and flaming will result in being IP banned at the very least. Treat others with kindness. All chat messages are logged. A bit of in-game-context trash talking is one thing. Turning our platform into a medium to bully others will result in punitive action, from banning your IP address to contacting appropriate authorities. Simple as that. Don't test us. I work with children for at least part of my living and as a result I take bullying and harassment very seriously.

Now that we have passed the Terms of Service, let's finish the last topic of the EULA--information use. Our server does have moderate forms of data capture, particularly during the registration phase. We collect the following information from users: a username, a password, and an email address. The latter can be omitted should a user wish not to share it; If you do provide it, it will be used to send automated emails for major project updates only, unless you subscribe to other things. This is the only information we collect, as a result, our server is COPPA-compliant, as we collect no personally identifiable information from anyone, let alone a minor. You may upload assets to the "Web Deck" to control different aspects of your LARP experience within this game, but again...this information is cosmetic and cannot be used to identify you in any way. If you are a parent whose child is interested in playing this game and you would like to know more, feel free to contact the Project devs using one of the three options provided in the footer at our Official Website.