/pocketpy

Open Source Python Interpreter in 1 File for Game Scripting

Primary LanguageC++MIT LicenseMIT

pocketpy: python interpreter in 1 file

C++17 GitHub GitHub release Website

English | 简体中文

pkpy is a lightweight(~15K LOC) Python interpreter for game scripting, built on C++17 with STL.

It aims to be an alternative to lua for game scripting, with elegant syntax, powerful features and competitive performance. pkpy is extremely easy to embed via a single header file pocketpy.h, without external dependencies.

Please see https://pocketpy.dev for details or try Live Demo.

Supported Platforms

pkpy should work on any platform with a C++17 compiler. These platforms are officially tested.

  • Windows 64-bit
  • Linux 64-bit / 32-bit
  • macOS 64-bit
  • Android 64-bit / 32-bit
  • iOS 64-bit
  • Emscripten 32-bit
  • Raspberry Pi OS 64-bit

Quick Start

Download the pocketpy.h on our GitHub Release page. And #include it in your project.

You can also use cmake to build it from source. See CMakeLists.txt for details. These variables can be set to control the build process:

  • PK_BUILD_STATIC_LIB - Build the static library (default, recommended)
  • PK_BUILD_SHARED_LIB - Build the shared library

It is safe to use main branch in production.

Compile Flags

To compile it with your project, these flags must be set:

  • --std=c++17 flag must be set
  • Exception must be enabled
  • For MSVC, /utf-8 flag must be set

For development build, use this snippet.

# prerequisites
pip install cmake
# build the repo
python cmake_build.py
# unittest
python scripts/run_tests.py

Example

#include "pocketpy.h"

using namespace pkpy;

int main(){
    // Create a virtual machine
    VM* vm = new VM();

    // Hello world!
    vm->exec("print('Hello world!')");

    // Create a list
    vm->exec("a = [1, 2, 3]");

    // Eval the sum of the list
    PyObject* result = vm->eval("sum(a)");
    std::cout << py_cast<int>(vm, result);   // 6

    // Bindings
    vm->bind(vm->_main, "add(a: int, b: int)",
      [](VM* vm, ArgsView args){
        int a = py_cast<int>(vm, args[0]);
        int b = py_cast<int>(vm, args[1]);
        return py_var(vm, a + b);
      });

    // Call the function
    PyObject* f_add = vm->_main->attr("add");
    result = vm->call(f_add, py_var(vm, 3), py_var(vm, 7));
    std::cout << py_cast<int>(vm, result);   // 10

    // Dispose the virtual machine
    delete vm;
    return 0;
}

Features

Check this Cheatsheet for a quick overview of the supported features.

Name Example Supported
If Else if..else..elif
Loop for/while/break/continue
Function def f(x,*args,y=1):
Subclass class A(B):
List [1, 2, 'a']
ListComp [i for i in range(5)]
Slice a[1:2], a[:2], a[1:]
Tuple (1, 2, 'a')
Dict {'a': 1, 'b': 2}
F-String f'value is {x}'
Unpacking a, b = 1, 2
Star Unpacking a, *b = [1, 2, 3]
Exception raise/try..catch..finally
Dynamic Code eval()/exec()
Reflection hasattr()/getattr()/setattr()
Import import/from..import
Context Block with <expr> as <id>:
Type Annotation def f(a:int, b:float=1)
Generator yield i
Decorator @cache

Performance

Currently, pkpy is as fast as cpython 3.9. Performance results for cpython 3.9 are applicable to for pkpy.

See https://pocketpy.dev/performance/ for details.

And these are the results of the primes benchmark on Intel i5-12400F, WSL (Ubuntu 20.04 LTS), which roughly reflects the performance among c++, lua, pkpy and cpython.

name version time file
c++ gnu++11 0.104s ■□□□□□□□□□□□□□□□ benchmarks/primes.cpp
lua 5.3.3 1.576s ■■■■■■■■■□□□□□□□ benchmarks/primes.lua
pkpy 1.2.7 2.385s ■■■■■■■■■■■■■□□□ benchmarks/primes.py
cpython 3.8.10 2.871s ■■■■■■■■■■■■■■■■ benchmarks/primes.py

Used By

Description
TIC-80 TIC-80 is a fantasy computer for making, playing and sharing tiny games.
MiniPythonIDE A python ide base on pocketpy
py-js Python3 externals for Max / MSP
crescent Crescent is a cross-platform 2D fighting and beat-em-up game engine.

Submit a pull request to add your project here.

Contribution

All kinds of contributions are welcome.

  • Submit a Pull Request
    • fix a bug
    • add a new feature
  • Open an Issue
    • any suggestions
    • any questions

If you find pkpy useful, consider star this repository (●'◡'●)

Sponsor this project

You can sponsor this project via these ways.

Your sponsorship will help us develop pkpy continuously.

Reference

  • cpython

    The official implementation of Python programming language.

  • byterun

    An excellent learning material. It illustrates how Python's virtual machine works.

  • box2d

    The world's best 2D physics engine, written by Erin Catto. box2d now becomes a built-in module in pkpy v1.1.3 and later.

Star History

Star History Chart

License

MIT License