English | 简体中文
pkpy is a lightweight(~14K 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.
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 64-bit
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 libraryPK_BUILD_SHARED_LIB
- Build the shared library
To compile it with your project, these flags must be set:
--std=c++17
flag must be set- Exception must be enabled
#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;
}
Check this Cheatsheet for a quick overview of the supported features.
Name | Example | Supported |
---|---|---|
If Else | if..else..elif |
YES |
Loop | for/while/break/continue |
YES |
Function | def f(x,*args,y=1): |
YES |
Subclass | class A(B): |
YES |
List | [1, 2, 'a'] |
YES |
ListComp | [i for i in range(5)] |
YES |
Slice | a[1:2], a[:2], a[1:] |
YES |
Tuple | (1, 2, 'a') |
YES |
Dict | {'a': 1, 'b': 2} |
YES |
F-String | f'value is {x}' |
YES |
Unpacking | a, b = 1, 2 |
YES |
Star Unpacking | a, *b = [1, 2, 3] |
YES |
Exception | raise/try..catch |
YES |
Dynamic Code | eval()/exec() |
YES |
Reflection | hasattr()/getattr()/setattr() |
YES |
Import | import/from..import |
YES |
Context Block | with <expr> as <id>: |
YES |
Type Annotation | def f(a:int, b:float=1) |
YES |
Generator | yield i |
YES |
Decorator | @cache |
YES |
All kinds of contributions are welcome.
- Submit a Pull Request
- fix a bug
- add a new feature
- Open an Issue
- any suggestions
- any questions
Check our Coding Style Guide if you want to contribute C++ code.
-
The official implementation of Python programming language.
-
An excellent learning material. It illustrates how Python's virtual machine works.
-
The world's best 2D physics engine, written by Erin Catto.
box2d
now becomes a built-in module in pkpyv1.1.3
and later.