diff --git a/README.md b/README.md index fe1453f0..3a6854dc 100644 --- a/README.md +++ b/README.md @@ -2,51 +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_ -## Structure +Documentation at -This project contains three folders: +## Overview -- `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. - +[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. -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. +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. ;) -### Binaries +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/). -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. +## User setup -### Unity Package +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 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*. +The Unity package is built and published to our registry on every merge to +master. -The Unity package is build and published to our registry on every merge to master. +# Use -## Setup - -You currently need Python and MPF installed locally. - -1. Install Python 3 -2. `pip install --pre mpf mpf-mc` - -Or, if you already have it: - -`pip install mpf mpf-mc --pre --upgrade` - -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 @@ -54,35 +47,26 @@ 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: ```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