From 8e22e7614fb2c6bd59c551b789a477933a2b2989 Mon Sep 17 00:00:00 2001 From: freezy Date: Mon, 24 Feb 2025 13:15:25 +0100 Subject: [PATCH 1/2] doc: Update README. --- README.md | 80 ++++++++++++++++++++++--------------------------------- 1 file changed, 32 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index fe1453f0..02f8910e 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,27 @@ *Enables the Mission Pinball Framework to drive VPE* -## Structure +## Overview -This project contains three folders: +[MPF](https://missionpinball.org/latest/about/) is an open-source framework +written in Python to drive real pinball machines. It has a "configuration over +code" approach, meaning that 90% of what you'd do in a pinball game can be +achieved through configuration (YAML files) rather than implementing it in code. -- `VisualPinball.Engine.Mpf` is a library which builds the gRPC protos and - wraps them into a nicer interface. -- `VisualPinball.Engine.Mpf.Test` is a command line tool that allows quick - testing without running Unity -- `VisualPinball.Engine.Mpf.Unity` is the Unity UPM package that plugs into - VPE and implements the gamelogic engine. - +When you read MPF's [Getting Started](https://missionpinball.org/latest/start/) +page, you'll notice a banner stating that "MPF is not a simulator." Well, +you've found the simulator. ;) -Currently, only the first two projects are contained in the provided VS -solution. In the future we might add the Unity project with its dependencies, -but for now you'll need to open it through Unity. +This project lets you use MPF to drive game logic in [VPE](https://github.com/freezy/VisualPinball.Engine), +a pinball simulator based on Unity. It does this by spawning a Python process running +MPF and communicating with VPE through [gRPC](https://grpc.io/). -### Binaries +### Installation -Both gRPC and Protobuf come with dependencies that conflict with Unity's, namely -`System.Buffers`, `System.Memory` and `System.Runtime.CompilerServices`. To -solve this, we disable assembly validation for `Google.Protobuf.dll` and `Grpc.Core.dll` -via the plugin inspector. - -### Unity Package - -The goal of this repo is to use it within Unity. In order to do that, open the -Package Manager in Unity, and add `org.visualpinball.engine.missionpinball` under -*Add package from git URL*. +This project is available as a Unity package at `registry.visualpinball.org`. +To install it, make sure the scoped registry is added in your Package Manager +settings. Then open the Package Manager in Unity and add +`org.visualpinball.engine.missionpinball` under *Install package by name*. The Unity package is build and published to our registry on every merge to master. @@ -59,32 +52,23 @@ actual binaries, `.meta` files of uncompiled platforms are cleaned up by Unity. In order to not accidentally commit those files, we recommend to ignore them: ```bash -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/linux-x64/VisualPinball.Engine.Mpf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/linux-x64/Google.Protobuf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/linux-x64/Grpc.Core.Api.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/linux-x64/Grpc.Core.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/linux-x64/libgrpc_csharp_ext.so.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/osx-x64/VisualPinball.Engine.Mpf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/osx-x64/Google.Protobuf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/osx-x64/Grpc.Core.Api.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/osx-x64/Grpc.Core.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/osx-x64/libgrpc_csharp_ext.dylib.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x64/VisualPinball.Engine.Mpf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x64/Google.Protobuf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x64/Grpc.Core.Api.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x64/Grpc.Core.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x64/grpc_csharp_ext.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x86/VisualPinball.Engine.Mpf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x86/Google.Protobuf.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x86/Grpc.Core.Api.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x86/Grpc.Core.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity/Plugins/win-x86/grpc_csharp_ext.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity\Plugins\linux-x64\System.Runtime.CompilerServices.Unsafe.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity\Plugins\osx-x64\System.Runtime.CompilerServices.Unsafe.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity\Plugins\win-x64\System.Runtime.CompilerServices.Unsafe.dll.meta -git update-index --assume-unchanged VisualPinball.Engine.Mpf.Unity\Plugins\win-x86\System.Runtime.CompilerServices.Unsafe.dll.meta +git update-index --assume-unchanged Plugins/Google.Protobuf.dll.meta +git update-index --assume-unchanged Plugins/Grpc.Core.Api.dll.meta +git update-index --assume-unchanged Plugins/Grpc.Net.Client.dll.meta +git update-index --assume-unchanged Plugins/Grpc.Net.Common.dll.meta +git update-index --assume-unchanged Plugins/Microsoft.Extensions.Logging.Abstractions.dll.meta +git update-index --assume-unchanged Plugins/System.Buffers.dll.meta +git update-index --assume-unchanged Plugins/System.Diagnostics.DiagnosticSource.dll.meta +git update-index --assume-unchanged Plugins/System.IO.Pipelines.dll.meta +git update-index --assume-unchanged Plugins/System.Memory.dll.meta +git update-index --assume-unchanged Plugins/System.Numerics.Vectors.dll.meta +git update-index --assume-unchanged Plugins/System.Runtime.CompilerServices.Unsafe.dll.meta +git update-index --assume-unchanged Plugins/System.Threading.Tasks.Extensions.dll.meta +git update-index --assume-unchanged Plugins/VisualPinball.Engine.Mpf.deps.json.meta +git update-index --assume-unchanged Plugins/VisualPinball.Engine.Mpf.dll.meta +git update-index --assume-unchanged Plugins/VisualPinball.Engine.Mpf.pdb.meta ``` ## License -[MIT](LICENSE) +[MIT](LICENSE) \ No newline at end of file From d07b9e88885ce355ed6248bfb398a39470241dde Mon Sep 17 00:00:00 2001 From: arthurkehrwald <50906979+arthurkehrwald@users.noreply.github.com> Date: Mon, 24 Feb 2025 23:04:44 +0100 Subject: [PATCH 2/2] Update README --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 02f8910e..3a6854dc 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,44 @@ [![UPM Package](https://img.shields.io/npm/v/org.visualpinball.engine.missionpinball?label=org.visualpinball.engine.missionpinball®istry_uri=https://registry.visualpinball.org&color=%2333cf57&logo=unity&style=flat)](https://registry.visualpinball.org/-/web/detail/org.visualpinball.engine.missionpinball) -*Enables the Mission Pinball Framework to drive VPE* +_Enables the Mission Pinball Framework to drive VPE_ + +Documentation at ## Overview -[MPF](https://missionpinball.org/latest/about/) is an open-source framework +[MPF](https://missionpinball.org/latest/about/) is an open-source framework written in Python to drive real pinball machines. It has a "configuration over -code" approach, meaning that 90% of what you'd do in a pinball game can be +code" approach, meaning that 90% of what you'd do in a pinball game can be achieved through configuration (YAML files) rather than implementing it in code. When you read MPF's [Getting Started](https://missionpinball.org/latest/start/) -page, you'll notice a banner stating that "MPF is not a simulator." Well, -you've found the simulator. ;) - -This project lets you use MPF to drive game logic in [VPE](https://github.com/freezy/VisualPinball.Engine), -a pinball simulator based on Unity. It does this by spawning a Python process running -MPF and communicating with VPE through [gRPC](https://grpc.io/). - -### Installation - -This project is available as a Unity package at `registry.visualpinball.org`. -To install it, make sure the scoped registry is added in your Package Manager -settings. Then open the Package Manager in Unity and add -`org.visualpinball.engine.missionpinball` under *Install package by name*. - -The Unity package is build and published to our registry on every merge to master. +page, you'll notice a banner stating that "MPF is not a simulator." Well, you've +found the simulator. ;) -## Setup +This project lets you use MPF to drive game logic in +[VPE](https://github.com/freezy/VisualPinball.Engine), a pinball simulator based +on Unity. It does this by spawning a Python process running MPF and +communicating with VPE through [gRPC](https://grpc.io/). -You currently need Python and MPF installed locally. +## User setup -1. Install Python 3 -2. `pip install --pre mpf mpf-mc` +This project is available as a Unity package at `registry.visualpinball.org`. To +install it, make sure the scoped registry is added in your Package Manager +settings. Then open the Package Manager in Unity and add +`org.visualpinball.engine.missionpinball` under _Install package by name_. -Or, if you already have it: +The Unity package is built and published to our registry on every merge to +master. -`pip install mpf mpf-mc --pre --upgrade` +# Use -After that, `mpf --version` should return at least **MPF v0.55.0-dev.37**. +1. Add the `MpfGamelogicEngine` component to the root object of your table +2. Click on 'Get Machine Desciption' in its inspector +3. Click on 'Populate Hardware' to bring the coils switches and lamps from MPFs + machine description into VPEs respective manager windows +4. Assign the coils, switches and lamps to items on your playfield using the + coil, switch and lamp manager windows ## Development Setup @@ -47,7 +47,7 @@ In order to import the package locally instead from our registry, clone and compile it. This will copy the necessary binaries into the Unity folder. Only then, import the project into Unity. -Since the Unity folder contains `.meta` files of the binaries, but not the +Since the Unity folder contains `.meta` files of the binaries, but not the actual binaries, `.meta` files of uncompiled platforms are cleaned up by Unity. In order to not accidentally commit those files, we recommend to ignore them: @@ -71,4 +71,4 @@ git update-index --assume-unchanged Plugins/VisualPinball.Engine.Mpf.pdb.meta ## License -[MIT](LICENSE) \ No newline at end of file +[MIT](LICENSE)