hierosoft / qbhle

QBHLE High-Level Emulator (formerly BluffBASIC) is for running QBASIC programs like console emulators run games: High-level emulation means improving the quality or convenience of the program while avoiding overhead & complexity of emulating low-level operations. Targets: QBasic 1.1; eventually enough QuickBASIC 4.5 features for 90s QB scene games.

Hierosoft Update

Solve Python distribution with a one-click install solution!

Integrate Python programs with the system in various ways:

• Request an assigned directory where files can be placed such as for icons (pixmaps), shortcuts, or cache.
  • hierosoft.get_unique_path
    • Has an "allow_cloud" option to detect a Nextcloud or ownCloud directory containing a "profile" directory (for the "Configs:Unique" option)
• Create a desktop shortcut in a way that works in any operating system.
  • from hierosoft.moreplatform import make_shortcut
• Get more metadata such as for images.
  • hierosoft.moremeta
• Emulate grep but also: Get a list of files; Process .gitignore files (and optionally get include and exclude filters for rsync).
  • from hierosoft.ggrep import (ggrep, gitignore_to_rsync_pair)
• Emulate netcat but get callbacks during the upload.
  • from hierosoft.moreweb import netcat
• See nonexistent paths that may be safe to remove from the environment's PATH variable.
  • hierosoft.checkpath
• See if your repo's latest tag matches the version stored in your repo.
  • hierosoft.checkversion
• Process URL requests in a Python 3 way regardless of the Python version.
  • hierosoft.moreweb

Filesystem shortcuts

• doc/join_if_exists.md

Example projects

(using this module)

• https://github.com/poikilos/blendernightly
• https://github.com/poikilos/world_clock

Core features

Hierosoft Update is the Python manager and virtualenv manager module to download or run a Python program such as an updated copy of:

• itself
• the Hierosoft Launcher (See Project Status).
• any program (when used by the launcher or blendernightly)

Checkpath

To learn more, see the comment (docstring) at the top of checkpath.py.

Project Status

• The gui_tk main function should be launched by the icon.
• In Windows, Hierosoft Icon should be compiled as an exe such as using PyOxidizer so that it runs without having to install anything first.
• Download and run itself (updated Python copy) as the main program which should run the launcher.
  • The process of installing apps should move to the launcher which should use the downloaded python version of this module.
• Complete the launcher a separate project and run that instead of running a single program.
  • Potentially, nopackage could become the launcher or a component in the same virtualenv). It has the advantage of having download locations of icons for certain programs.
  • Make a special virtualenv named hierosoft-launcher that only contains what Hierosoft Launcher needs to operate, and a copy of Hierosoft Update.
• Add https://pypi.org/project/eric-ide as a test case except use ~/.virtualenvs. Keep the eric7_venv directory if it exists in case manual steps were used prior.
  • Remember to include eric7_post_install.
• Check for an existing venv directory such as if ~/venv/kivy were used according to manual instructions.

Development

Purpose

The purpose of Hierosoft Update is to ensure that the launcher can start, and serve as a platform for installing other Python programs as well. The way the Hierosoft Update works is by setting up a virtualenv for a program or set of programs after trying to detect the correct version of Python regardless of how the program is packaged.

The Python distribution dilemma is that programs are scripts users must open unless the author puts some custom system in place to install an icon and to do one of the following:

• Ensure a correct Python version is installed, and where it is.
• Compile the Python code into an exe such as using PyOxidizer.

The dilemma is that though solutions exist, there isn't a de facto standard other than solutions which already assume you have Python and require Command-Line Interface (CLI) commands.

qbhle's Issues

Consider emulating OPL3 for sound effects

Some games (The Secret of Cooey??) may use the OPL3 chip for sound effects.

Possible ways to deal with this:

• https://github.com/datajake1999/OPL3GM_VSTi
• Redeem OPL3 by making a superior OPL3HLE that is an abstraction layer over a CZ-101 (Phase Distortion synthesizer) emulator: https://gearspace.com/gear/plugin-boutique/virtualcz?via=gear_post_link

Underclock TIMER

As for actually using TIMER for framerate locking, I will try to find an example, otherwise post here if you know of any.

• The hardware tick is divided by 18.2 to avoid overflows in the TIMER variable: https://www.tek-tips.com/faqs.cfm?fid=917

I suppose (optionally) accessing TIMER could actually sleep CPU when the TIMER global is accessed. Let CPU rest 1ms maybe? The math would have to be worked out, but that may be fine enough since even locking to 60fps is 16.6... [repeating 6] ms so it is probably fine-grained enough.

Just demos, so it is hard to tell if speed is as expected:

• (GWBasic) https://github.com/RetroNick2020/Channel-Code/blob/877fec0476aed034439f77b0c420a090e52390a9/gwbasic/NH.BAS
• https://github.com/robhagemans/hoard-of-gwbasic/blob/d4e65c52d782ba03f69fb15ea7a97a9b13e41bdd/ProgrammersHeaven/SNAKES3.BAS#L9

---

Implement numeric overflow protection

• INT is 16-bit signed
• LONG is 32-bit signed
• SINGLE is 16-bit signed float
• DOUBLE is 32-bit signed float

https://vedrank90.wordpress.com/2009/12/13/qbasic-data-types/

Add HLE for MIDI

Libraries to potentially use/improve:

• https://github.com/vishnubob/python-midi (MIDI parser)
• https://github.com/sinshu/py-meltysynth (SoundFont + MIDI => audio renderer) -- needs optimization
• https://pypi.org/project/mido/ - supports Pygame; used by Stargate DAW

Add terminator character?

• See "\032" in https://github.com/nocoolnicksleft/basic-parser/blob/master/t1.l

Implement "subscript out of range"

• Max integer is 2^15-1 (= 32767)
• However 2D arrays are limited further: size 180, 180 (subscripts 179,179)?? see mathematically conflicting statements at this odd answer: https://qbasic-forum.qbasic.net/qbasic-related/there-maximum-size-for-array-t549.html) since it is just a shortcut for dim2*width+dim1!
• occurs if type is not int (whole number)! See MemReflect's answer: https://stackoverflow.com/a/62295341/4541104
• "Arrays that are not explicitly declared can only have 11 items with an index from 0 to 10" -MemReflect https://stackoverflow.com/a/62295341/4541104

Requires:

• #3 (required since the new max int constant can be reused)

Add underclocking

• #8
• #9
• #10

Consider adding more baselines

(Maybe after 1.0)

QBasic 4.5

• https://github.com/Zannick/qbasic-programs

Various targets

RPGDX

QB Games Showcase at the RPGDX (RPG competition)

• https://web.archive.org/web/20160109194849/http://rpgdx.net/
  • formerly https://web.archive.org/web/20030226095752/http://www.indie-rpg.net/rpgdx/index.php
    • as discussed at http://vplanet.petesqbsite.com/arch187.shtml
  • bjorn/rpgdx#4

basic-games

• https://github.com/chaosotter/basic-games/blob/4f8f837e07139cd4235921c46e9254b24a825f77/games/Rainbow/1983-04/Horse%20Racing/game.bas#L35
• and others in https://github.com/chaosotter/basic-games

raster-master

• https://github.com/RetroNick2020/raster-master/tree/5643abe6257bb8058f359db64d97b6db98470ae9/Examples/qbasic

Civil War Strategy Game

• https://github.com/davidshq-legacy/Civil-War-Strategy-Game/blob/dac8db1dd37af834eec49b89a5a35e87f115e7d9/CWSTRAT.BAS#L3957

goalieca

• https://github.com/goalieca/ancient-code1/tree/master

brisray

• https://brisray.com/qbasic/qdload.htm
  • https://brisray.com/qbasic/qdelay.htm

QB64

Rattler

• https://github.com/DualBrain/QB64/blob/eb9b8c9cad488bd1304035e1bfc5d2e89b0f78df/samples/rattler/src/rattler.bas#L10

Underclock WAIT if followed by a screen refresh memory address

• WAIT &H3DA, 8: waits for next screen refresh--This is probably the most reliable method, though is technically affected by hardware (such as 120 Hz displays or CRTs with odd refresh rates) and therefore would also need underclocking to produce expected behavior. Examples:
  • https://brisray.com/qbasic/qdelay.htm (uses WAIT &H3DA, 8, 8 on next line, not sure why)
  • WAIT &H3DA, 8: https://github.com/goalieca/ancient-code1/blob/master/breakout-qbasic/BREAKOUT.BAS
• WAIT 938, 8 I'm not sure why this is used instead of WAIT &H3DA, 8 (3DA is 986 in decimal; 938 would be 3AA), but it runs a little fast on my 60Hz display on Fedora 38 and the reason is not clear. Example: Spinball at https://www.qbasic.net/en/qbasic-downloads/games/action-3.htm

Set default type

• DEF* statements change the default

SINGLE (DEFSNG) is the default for:

• variables
• DEF FN functions
• FUNCTION procedures
• "After you specify a DEFtype statement in your program, QBasic automatically inserts a corresponding DEFtype statement in each procedure you create." -https://www.qbasic.net/en/reference/qb11/Statements/DEFtype.htm
• suffix overrides default

Implement changing of default type

https://www.qbasic.net/en/reference/qb11/Statements/DEFtype.htm

• Default is initially Single (See #3 for sizes)

Related issues:

• #3

Where is the parser?

Find a good enough BASIC parser in YACC (or descriptor in another lexer/parser format that has a pure Python module).

• https://github.com/nocoolnicksleft/basic-parser

Awaiting license

• zkfbdkf/BASIC-interpreter#1
• meteccinar/YaccBasicCompiler#1

Underclock number of operations performed (FLOPS)

• An example requiring a change to processing speed in general (doesn't use TIMER for frame rate locking, just assumes CPU speed): https://www.jefflewis.net/programming-qbasic-tankgame.html#source

For games that just assume a clock speed and don't even do frame locking, it would be possible to count the number of FLOPS and limit the FLOPS that way, placing the delay wherever math is done too many times per second.

Implement RND precisely

"...returns a number between 0 and 1, excluding 1..."
-MemReflect on https://stackoverflow.com/questions/62278164/how-do-i-fix-the-error-subscript-out-of-range-in-qbasic

It excludes the upper number on multiplying:

• So RND * 5 is probably interpreted as int(random() * 5) (It never reaches 5).

DECLARE is required if you call SUB procedures without CALL

See https://www.qbasic.net/en/reference/qb11/Statement/DECLARE.htm