Pyjsdl Module Guide

Pyjsdl module is modelled on Pygame/SDL commands that wraps JavaScript functionality including HTML5 canvas. To use Pyjsdl module, place pyjsdl folder in the script folder or on the module path. Import pyjsdl into the Python script, or use the statement 'import pyjsdl as pygame' to maintain the Pygame commands. During pyjsdl initiation, use the statement pyjsdl.setup(run, images) to provide the canvas the main function to execute at a timed interval and program images to preload, where the 'run' function contains statements derived from the main loop to be repeated each frame and 'images' is a list of image paths in the form ['./images/img.png'].

Python code using Pyjsdl is compiled to a JavaScript application with the Transcrypt compiler (https://www.transcrypt.org/). Install Transcrypt according to its documentation (https://www.transcrypt.org/docs/html/index.html). Transcrypt 3.9 should be installed under Python 3.9, preferably in a virtual environment. A possible approach is to install Python 3.9 on your development system and create a virtual environment and pip install Transcrypt, for instance on Linux:

python3.9 -m venv env
source env/bin/activate
pip install --upgrade pip setuptools wheel
pip install transcrypt

To compile script.py, use the command 'transcrypt -n script.py' that will compile to the __target__ folder. Place data folder in script folder. Create script.html file in script folder to launch the code, with a script link to the compiled JavaScript app and an element with id '__panel__' to which the canvas will be added, for instance:

<!doctype html>
<html>
<body>
    <h2>Pyjsdl App</h2>
    <div id="__panel__"></div>
    <script type="module" src="__target__/pyjsdl_app.js"></script>
</body>
</html>

The script.html file can be launched direct, or loaded in another Web page using:

<iframe src="https://computer.com/app_folder/script.html" marginwidth="0" marginheight="0" hspace="0" vspace="0" scrolling="no" width="400" height="300" frameborder="0"></iframe>

Some additional changes to the Python script may be necessary for Transcrypt compilation. A web application, consisting of script html file along with __target__ and optional data folders, can be deployed following compilation to JavaScript, which can run in a web browser on a pc or mobile. To run on a local HTTP server, use command 'python3 -m http.server' and browse to localhost:8000. During development, use the web browser devtools console that displays print and error output, and to maintain updated development changes set devtools to open with cache disabled. The app can also run on the desktop using the app.py script, check instructions within the script.

The module can also be used from a JavaScript application. Create a folder containing the Transcrypt-compiled module with the command 'transcrypt -n main.py -od pyjsdl-lib' and place a link to 'pyjsdl-lib/main.js' in a script.html file, for instance:

<!doctype html>
<html>
<body>
    <h2>Pyjsdl JS App</h2>
    <div id="__panel__"></div>
    <script type='module' src="pyjsdl-lib/main.js"></script>
    <script defer src="./js_app.js"></script>
</body>
</html>

The module should be available in JavaScript as 'pyjsdl', also available as 'window.pyjsdl', and can be accessed through the module's API. There are some minor differences with JavaScript access. Since JavaScript does not have a tuple type, any pass of tuple argument to the module should be a JavaScript Array [], for instance 'pyjsdl.Surface([w,h])'. Displaying object information with console.log can be done with 'object.toString()'. Other than these few differences, the JavaScript application can utilize the module similar to described for a Python application, and providing a callback to pyjsdl.setup() to run the application.

For efficiency Transcrypt uses __pragma__ directives to handle Python special methods, as described in Transcrypt documentation. The __pragma__ directive can be placed at the start of the script, or more efficently by surround code with the directive. For instance, iteration of a dictionary keys can be done:

option1:
for key in adict.keys():
    print(key)
option2:
# __pragma__ ('iconv')
for key in adict:
    print(key)
# __pragma__ ('noiconv')

For Python object truth value such as checking empty list:
alist = []
option1:
if len(alist) == 0:
    print('empty list')
option2:
# __pragma__ ('tconv')
if not alist:
    print('empty list')
# __pragma__ ('notconv')

For function keyword args:
# __pragma__ ('kwargs')
def inc(a, b=1):
    return a+b
# __pragma__ ('nokwargs')

For objects, operator and index functionality requires __pragma__ ('opov'). This is required for these functionality for Pyjsdl modules rect, vector, and pyjsarray. For instance place "# __pragma__ ('opov')" at the top of the script or surround specific code as:

# __pragma__ ('opov')
rect = Rect(0,0,10,10)
x = rect[0]
y = rect[1]
# __pragma__ ('noopov')

For Python statements to be skipped by Transcrypt, use __pragma__ ('skip'):

platform = None
# __pragma__ ('skip')
import pygame
platform = 'pc'
# __pragma__ ('noskip')
if not platform:
    import pyjsdl as pygame
    platform = 'js'

Further information is available on the Pyjsdl project page (https://gatc.ca/projects/pyjsdl-ts/) and in the API documentation (https://gatc.ca/projects/pyjsdl-ts/doc/).

