diff --git a/docs/unity/bindings.md b/docs/unity/bindings.md index afe2241c..87ca4b91 100644 --- a/docs/unity/bindings.md +++ b/docs/unity/bindings.md @@ -155,8 +155,7 @@ And set the returned object into a module. Here we set it into `builtins` module, so that it can be accessed from anywhere. ```csharp -var type = vm.RegisterType(new PyVector2Type()); -vm.builtins.attr["Vector2"] = type; +vm.RegisterType(new PyVector2Type(), vm.builtins); ``` To summarize, manual static bindings provide detailed control for exposing a C# class to Python. @@ -169,8 +168,7 @@ Automatic static bindings use C# reflection to automatically generate bindings f It is convenient for testing and prototyping, but it is slow and unsafe since the user can access any member of the class. ```csharp -var type = vm.RegisterAutoType(); -vm.builtins.attr["Vector2"] = type; +vm.RegisterAutoType(vm.builtins); ``` That's all you need to do. The `RegisterAutoType` method will automatically generate bindings for `Vector2`. diff --git a/docs/unity/introduction.md b/docs/unity/introduction.md index 965d680b..26170b68 100644 --- a/docs/unity/introduction.md +++ b/docs/unity/introduction.md @@ -4,16 +4,79 @@ icon: dot order: 30 --- -# Welcome to PocketPyUnity +# Welcome to PocketPython -PocketPyUnity is a C# plugin that allows you to do Python scripting in [Unity](https://unity.com/). -It provides a sandboxed Python environment, adding dynamic capabilities to your game, -which can be used for dynamic game logic, modding, hot fixing, and more. +PocketPython is a C# plugin that allows you to do Python scripting in Unity. It provides a sandboxed Python environment, which adds dynamic capabilities to your game, which can be used for dynamic game logic, modding, hot fixing, and more. -The virtual machine is written in **pure C#**, -which means you can fully control the internal state of the Python interpreter. +The virtual machine is written in pure C#, which means you can fully control the internal state of the Python interpreter. !!! -PocketPyUnity is designed for game scripting, not for scientific computing. +PocketPython is designed for game scripting, not for scientific computing. You cannot use it to run NumPy, OpenCV, or any other CPython extension modules. -!!! \ No newline at end of file +!!! + + +## Features + +### Python 3.x Syntax + +PocketPython uses [pocketpy](https://github.com/blueloveTH/pocketpy) +as frontend to parse and compile Python source code. +It supports most of the Python 3.x syntax. + +The following table shows a feature comparison of PocketPython +with respect to the original [pocketpy](https://github.com/blueloveTH/pocketpy). +The features marked with `YES` are supported, and the features marked with `NO` are not supported. + +| Name | Example | Cpp | Unity | +| --------------- | ------------------------------- | --------- | --- | +| If Else | `if..else..elif` | YES | YES | +| Loop | `for/while/break/continue` | YES | YES | +| Function | `def f(x,*args,y=1):` | YES | YES | +| Subclass | `class A(B):` | YES | YES | +| List | `[1, 2, 'a']` | YES | YES | +| ListComp | `[i for i in range(5)]` | YES | YES | +| Slice | `a[1:2], a[:2], a[1:]` | YES | YES | +| Tuple | `(1, 2, 'a')` | YES | YES | +| Dict | `{'a': 1, 'b': 2}` | YES | YES | +| F-String | `f'value is {x}'` | YES | YES | +| Unpacking | `a, b = 1, 2` | YES | YES | +| Star Unpacking | `a, *b = [1, 2, 3]` | YES | YES | +| Exception | `raise/try..catch` | YES | NO | +| Dynamic Code | `eval()/exec()` | YES | NO | +| Reflection | `hasattr()/getattr()/setattr()` | YES | YES | +| Import | `import/from..import` | YES | YES | +| Context Block | `with as :` | YES | NO | +| Type Annotation | `def f(a:int, b:float=1)` | YES | YES | +| Generator | `yield i` | YES | NO | +| Decorator | `@cache` | YES | YES | + +### Sandboxed Python Environment + +PocketPython provides a sandboxed Python environment. +All python code is executed in a C# virtual machine. +The user cannot access the file system, network, or any other resources of the host machine. + +### Seemless Interop with C# + +PocketPython uses `object` in C# to represent dynamic typed Python objects. +Most of the basic Python types correspond to a C# type, +which means passing arguments between C# and Python is extremely easy and intuitive. + +| Python Type | C# Type | +| ----------- | ------- | +| `None` | `PocketPy.NoneType` | +| `bool` | `System.Boolean` | +| `int` | `System.Int32` | +| `float` | `System.Single` | +| `str` | `System.String` | +| `tuple` | `System.Object[]` | +| `list` | `System.Collections.Generic.List` | +| `dict` | `System.Collections.Generic.Dictionary` | +| ... | ... | + +### Lua Style API + +PocketPython also provides a Lua style API for C# in `LuaBindings` class. +It uses cpp implemented virtual machine instead of C# virtual machine. +It is faster than C# virtual machine, but it is not sandboxed. \ No newline at end of file