Mystic BBS Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Getting Started with Scripting =====

//Note: This section assumes you've already performed the installation of
Mystic Python as covered in the [[python_install|Installation]] section.//

This section will cover the very basics for creating your first
Mystic Python script.  A full function reference for all of the
Mystic BBS module will be covered in a [[python_functions|different]] section.

The goal of this section is not to teach you Python, but to show you
how to get started specifically with Mystic's embedded Python.  There are
many Python references and tutorials all over the Internet to help develop
the skills needed to create your Python programs.  Python is a very popular
scripting language used both at the hobby and professional levels, and the
resources available via Google are plentiful.


----
==== Creating a Script ====

A Mystic Python script is simply a text file with Python code in it
which can be executed by a number of ways within Mystic BBS.  These
can be edited with a source code editor or any text editor.

A script typically ends with the file extension of .mpy which stands
for "Mystic Python."  This is the current recommended naming convention
but in reality a script can have any name or extension that the developer
desires to use.

=== Import Mystic Module ===

For each script, you first must import the Mystic BBS module at the top of
your script by adding this line:

  import mystic_bbs as bbs

This will give you all of the BBS related functions addressable with a bbs
prefix.  For example, you would write a line of text to the user with full
MCI code support by using the prefix and function name:

  bbs.writeln("This is a test!")

Alternatively you could import the Mystic BBS module without a prefix so that
you can access the function names directly.  Keep in mind that if you do this
it is possible that a function name in the Mystic BBS library could conflict
with another function name in a different module:

  from mystic_bbs import *
  
This will give you access to all of the Mystic BBS functions without the need
of a prefix, for example:

  writeln("This is a test!")

Once this line has been added to the top, then the rest of the script contains
your Python code.  A very simple first script that simply prints "Hello World"
to the user and then shows the pause prompt would look like this:

  from mystic_bbs import *
  
  writeln("Hello world!")
  writeln("|PA")


Refer to the [[python_functions|function reference]] and [[python_examples|Python examples]] section for more information on Python functions available as part of the Mystic module.  Third party Python modules can also be installed and used within your Python scripts.

----
==== Executing a Python Script ====

There are numerous ways in which a Python script can be executed within
Mystic BBS and this section assumes an understanding of how to create
new menu commands, and how to edit prompts.

=== By Menu Command ===

Python scripts can be executed from your menus by using the "GY" menu
command for Python 2, or the "GZ" menu command for Python 3.  By default
Mystic looks in the theme's script directory for .mpy files using the
same logic that Mystic Programming Language uses.

  * If you supply a file with no extension, Mystic will add .mpy to it
  * If you do not supply a path, Mystic will look in the theme's script directory and finally the default script directory if theme fallback is enabled.
  * If you supply a full path and filename, Mystic will execute it.

For example:

  Menu Command: GY (Execute Python 2 Script)
          Data: testpython

The above example will execute "testpython.mpy" from the theme's script
directory if it exists.  If it is not found, then it will try to do the
same from the default script directory if "theme fallback" is enabled.

To execute Python 3, you'd use the GZ menu command instead of GY.

=== By Prompt Replacement ===

Any prompt can be replaced by a Python script by beginning the prompt with
a # character followed by the filename.  The script will execute from the
theme's script directory.  For example:

   001 #mypython

The above example would execute mypython.mpy with Python 2.7 from the theme's script
directory in place of system prompt #001.

To execute a Python 3 script from a prompt, use the ~ character instead of #

=== By Command Line ===

Mystic Python scripts can be executed directly from the command line by
using the -Y and -Z options, but keep in mind a username and password must be
supplied along with it.  For example:

  mystic -uSysop -ppassword -ytestpython
  
The above example will execute Python 2 script testpython from the user's theme script
directory applying the same logic as defined above for the path/filename
conversions in Mystic Python.  To execute Python 3 script from command line, use -Z
instead of -Y.

=== Through MPL Hooks ===

Mystic has hooks in various locations where functionality of Mystic can be completely replaced by MPL scripts, such as the user login and new user application processes.  It is possible to use these MPL hooks to call a Mystic Python script using the MenuCmd MPL function.

This type of approach would allow the entire login and new user application process to be completely scripted in Python, for example.  Your BBS could then call another script from a start menu to completely replace the menu system. 

A BBS can range from a completely scripted experience, to a completely customized theme without using any scripting, or anything in between.