This tutorial shows how to setup your initial development environment for developing apps on the Multimorphic P3 Platform.
The P3 Development Environment currently only runs on Windows.
Sign in to multimorphic.com, you can sign up for free.
Download the P3 SDK from https://www.multimorphic.com/support/projects/customer-support/wiki/3rd-Party_Development_Kit
Extract the SDK, for example in C:\P3, this will create C:\P3\P3_SDK_V0.8
Open C:\P3\P3_SDK_V0.8\P3SampleApp\Documentation\html\index.html in your browser and read the documentation.
The Getting Started section is a good starting point.
Copy c:\P3\P3_SDK_V0.8\.multimorphic to your user home directory
On Windows, that will be %HOMEDRIVE%%HOMEPATH%
You can type that expression as is in Windows File Explorer address bar.
For example, %HOMEDRIVE%%HOMEPATH% might expand to c:\Users\john
Join the P3 Community Discord at https://discord.gg/GuKGcaDkjd
You can ask your questions in the dev-forum under the 3RD PARTY DEVELOPMENT section.
The P3 SDK requires Unity 5.6.7. A newer version of Unity will not work.
This explains why macOS is not supported. Unity 5.6.7 is a 32-bit application and macOS dropped support for 32-bit starting with macOS Catalina in 2019.
The Unity 5.6.7 installer makes it very easy to install and integrate with Visual Studio 2017.
You should consider installing Visual Studio 2022 instead, it takes just a few more steps.
See the Visual Studio 2022 section below for details.
Whatever Visual Studio version you choose now, you can easily switch later.
Do not download Unity from the Unity Hub. You will end up with compiler issues.
Instead download Unity 5.6.7 for Windows at https://unity.com/releases/editor/archive
Choose Downloads (Win) > Unity Installer
Run the installer
When asked to Choose Components:
Visit unity.com, click on the silhouette in the top right corner and select Create a Unity ID
Start Unity and Login with your Unity ID.
If the firewall pops up, allow access to your private network.
On the first execution, select Unity Personal for the free version.
The organization you represent must not make more than $100K in revenue to use the free version.
Click Open in the top right corner.
Navigate to c:\P3\P3_SDK_V0.8, select P3SampleApp, click Select Folder.
It will take a while the first time the project is loaded. Unity has to import all the assets.
The next time the project is loaded will be much faster.
The Project window should be in the lower left corner. If you made changes and lost sight of the Project window, you can bring it back by selecting Window > Layouts > Default in the main menu.
In the Project window, select Scenes.
Double-click the Bootstrap scene to load it in the editor.
Click the play button (triangle icon).
NOTE: If all you see is a blue sky over grey ground, you have not selected a scene yet.
Double-click on the Bootstrap scene to load it.
NOTE: If you get weird errors:
It will say: Unable to Read Certificate, that's normal when running in the simulator.
The scene is zoomed in, to zoom out, in the top left corner of the scene view, click on Free Aspect, select Standalone
Press s to start a game
Press l (lowercase L) to launch a ball
Drag the left mouse button to move the ball
Press 0 (zero) to drain
Press [ to change the volume
Press [ and l (lowercase L) to open the service menu
Press a for the left flipper (navigate left)
Press ; for the right flipper (navigate right)
Press l (lowercase L) to confirm
In the top left corner of the Game view, click Display 1 then select Display 2 to see the backbox display (static image on P3SampleApp)
Click Display 2 then select Display 8 to see the LED simulator
Click Display 8 then select Display 1 to go back to the playfield view.
To rearrange the Unity Layout, you can grab a panel separator and slide perpendicularly to adjust the relative sizes.
To Add a tab to an existing panel, click the menu icon in the top right corner of the panel (look for the tiny 3 horizontal bars),
then select Add Tab and the type of tab you want. For example, select Add Tab > Game to add a second Game tab as a sibling of the existing Game tab.
To be able to view the two Game tabs simultaneously, they need to be in different panels.
Grab the title of one of the Game tabs and move it around to create a new panel or join an existing panel.
Select Display 1 in the first Game tab, and select Display 2 or 8 in the second Game tab.
You can now see both displays simultaneously.
If you like your Layout, you can save it with Window > Layouts > Save Layout.
If you want to go back to the original Layout, select Window > Layouts > Default.
There is also a dropdown button to choose the Layout in the top right corner of Unity.
This section explains how to integrate Visual Studio 2017 in Unity if you installed Visual Studio 2017 separately from Unity.
If you installed Visual Studio 2017 through the Unity installer, skip this step since it is already done.
If you prefer to work with Visual Studio 2022, skip to the next section.
In Unity, select Edit > Preferences in the main menu
Click External Tools in the left menu
Click to the right of External Script Editor, in the dropdown, select Visual Studio 2017 (Community Edition)
If you don't see it, select Browse, and select the Visual Studio 2017 integrated environment executable.
For example, navigate to "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE" and select devenv.exe
Click Open to finish your selection.
External Script Editor now says: Visual Studio 2017
Make sure the Editor Attaching option is selected
Launch Visual Studio 2017.
In Visual Studio 2017, select Tools > Extensions and Updates in the main menu.
In the search box, type Tools for Unity.
Install Visual Studio 2017 Tools for Unity if not already installed.
Upgrading the IDE to Visual Studio 2022 is worth it. Unity 5.6.7 is not fully compatible with Visual Studio 2022 but the inconveniences are very minor. Thanks to Ian Harrower for showing how to do this.
If you intend to use Copilot, we recommend Visual Studio 17.10 or higher to use the unified Copilot extension.
Visual Studio 2022 Community Edition is free for individuals.
Visit https://visualstudio.microsoft.com/downloads/ and select the Community Edition or another edition if you have a paid subscription.
This will install and launch the Visual Studio Installer.
Click on the Available tab and select Visual Studio Community 2022.
It may ask you to update the Visual Studio Installer before proceeding.
When upgrading the installer, you may get an error that “Something went wrong”. Just continue, it usually works fine. Otherwise, quit the Visual Studio Installer and launch it again. It will not ask to upgrade a second time.
In the Workloads tab, scroll down and select “Game Development with Unity”.
Click Install in the lower right.
In Unity, select Edit > Preferences in the main menu
Click External Tools in the left menu
Click to the right of External Script Editor, in the dropdown, select Browse
Navigate to " C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE" and select devenv.exe
Click Open to finish your selection.
External Script Editor now says: Visual Studio 2022
Make sure the “Editor Attaching” option is selected.
Click X in the top right corner to close the dialog.
If X is not enabled, the work-around is to select “General” above “External Tools”, this will enable X.
When you open a Unity project by double-clicking on a script source file in Unity, Visual Studio 2022 will complain:
This Unity project was not generated for the Visual Studio Tools for Unity. In your Unity Editor, please go to Preferences > External Tools and select Visual Studio for a better experience.
This is one of the minor inconveniences when using Visual Studio 2022 with Unity 5.6.7
Since that option does not exist in Unity 5.6.7, simply click “Do not warn me again” to the right of the warning.
The project solution works regardless of the warning. For example, you can check if the scripts compile cleanly. Right-click the Assembly-CSharp project in “Solution Explorer” and select Rebuild.
The real build occurs with the Multimorphic package builder anyway.
Also consider configuring Copilot, see the Copilot section below for details.
In Unity, in the Project window, expand Scripts and select Modes.
Double-click on P3SABaseGameMode.cs
Visual Studio will launch automatically.
If it asks you to sign in, click Not now, maybe later.
If the firewall pops up, allow access to your private network.
In the editor window of P3SaBaseGameMode, right-click the constructor:
public P3SABaseGameMode (P3Controller controller)
and select Breakpoint > Insert breakpoint
Make sure the game is not playing in Unity.
If the game is playing, click the Play button to stop it.
This is to make sure you hit the breakpoint which occurs at the start of the game.
Back in Visual Studio, attach to Unity like this:
In the dialog that appears, select the Unity process in the list and click OK.
Only Unity processes are listed, this makes the selection easy.
In Unity, click the Play button to start the game.
The game will be stopped at the breakpoint.
You can inspect variables in the lower left window.
You can inspect the Call Stack in the lower right window.
You can single step using the toolbar icons or the Debug menu.
You can resume execution by clicking Continue.
Click the stop icon (red square) or select Debug > Stop Debugging to stop debugging Unity.
This is optional.
Copilot is a coding assistant powered by AI. It can offer code completions and answer technical questions. Once you get a taste of it, you can never go back.
Copilot is available through GitHub. Copilot is not free, though there is a free 30-day trial. The cost for individuals is about $10/month. You might also have access through an enterprise subscription at work.
The following steps assume you already have access to a Copilot subscription, otherwise you can get started with your Copilot subscription here.
We also assume the GitHub Copilot extension was installed when Visual Studio 2022 was installed. This is automatic when selecting the “Game Development with Unity” workload.
Copilot is available for a handful of IDEs including Visual Studio 2022 v17.8 or higher.
To use Copilot in Visual Studio, you first have to login to your Microsoft account.
In Visual Studio 2022, select File > Account Settings in the top menu. A dialog opens.
If not already signed in to your Microsoft account, click Sign In. Enter your Microsoft account credentials.
The next step is to add your GitHub account.
To the right of “All Accounts”, click +Add, and select GitHub account.
Choose between an individual GitHub account or else a GitHub Enterprise account if you have access at work.
Click Close in the lower right corner to close the account dialog.
The “GitHub Copilot” icon (in the top right corner of Visual Studio 2022) will show a green checkmark if your GitHub account has access to Copilot.
You can now type normally in the Editor and Copilot will suggest code completions. You can also select the Copilot Chat window (next to the Solution Explorer) and ask Copilot questions.
This is optional.
Code snippets are templates that help inserting common code fragments.
Michael Ocean has provided a collection of code snippets to simplify the development of P3 applications.
Create the directory c:\P3\CodeSnippets\P3
Download all the files with the .snippet extension from here:
https://discord.com/channels/730055502557610004/1100893730820587711
and save them in c:\P3\CodeSnippets\P3
Note: the files with the .code-snippets extension are for Visual Studio Code which is not compatible with Visual Studio 2017.
To import the code snippets, select Tools > Code Snippet Manager in the main menu of Visual Studio.
Change the Language to CSharp.
Click Add
Navigate to C:\P3\CodeSnippets, select the P3 directory and click Select Folder.
You can see the code snippets have been imported by expanding the P3 folder.
Click OK to close the Code Snippet Manager.
To insert a snippet, choose one of these ways:
- Select Edit > IntelliSense > Insert Snippet
- Right-click in the code editor, select Snippet > Insert Snippet
- Press Ctrl+K,Ctrl-X
This is optional.
You can create a shared drive on the computer and configure the P3 machine to access it. This lets you install your application over the network and later copy logs to the computer for analysis. This has the potential to really streamline the development process. The alternative is to transfer the application package and logs using a USB drive.
The option to use the SMB network share is hidden by default to avoid confusing non-developers.
To use an SMB network share, you first need to enable the option and configure the login. This needs to be done only once. (Those instructions are for Windows 11. Adjust the instructions for your version of Windows accordingly.)
In the search bar, type cmd, right click on Command Prompt, select Run as administrator.
In the Terminal window, type: net user <username> <password> /add
For example: net user p3 changeit /add
Choose a better password than changeit.
In the Terminal window, type: ipconfig
Find the line that says: IPv4 Address
Write down the address, it will look like 192.168.2.10 but with different numbers.
Create a folder you want to share. For example: C:\P3\P3Share
Right click the folder in Windows Explorer, select Properties, select the Sharing tab, click Share…
Type the local user name in the text box. For example, type P3. Click Add.
The default permission is read only, this works to install packages.
To be able to copy logs, you need to give read-write permissions: click on Read and select Read/Write for the P3 user.
Click Share.
Click Done.
With System Manager running, open the coin door and press the Launch button. The Settings menu appears.
Select Developers.
Change “Allow installs from SMB” to Yes
Select Login.
Enter the Password.
Enter the computer IP address.
Enter the network share name. For example: P3Share
Enter the user name. For example: P3
This is important. The settings will take effect the next time you start System Manager.
See the section “Install from LAN Drive” below for further instructions.
From the top menu in Unity, select Multimorphic > Package App For Distribution
A dialog appears.
The Compatible Module Ids is a comma-separated list of module Ids that work with the application. See the table of Module Ids below. Choose Any if the application works with any installed module. Leave the field blank if the application can work with any module installed or no module installed.
Module ID | Module Name |
CL | Canon Lagoon |
LL-EE | Lexy Lightspeed – Escape from Earth |
CCR | Cosmic Cart Racing |
Heist | Heist |
WAMONH | Weird Al’s Museum of Natural Hilarity |
Drained | Drained |
FR | Final Resistance |
Any | Application works on any installed module |
<blank> | Application works on any installed module or no module installed |
The SDK Guide says “Feature Flags” is a comma-separated list of feature flags; usually used if there are build variations. The Tags is a comma-separate list of tags; future versions of the P3's Launcher carousel will sort/filter based on Tags.
Enter the requested values in the dialog.
For example, enter these values to build P3SampleApp:
Display Name: P3SampleApp
Version: 1.0.0.0
Description: Sample Application
Compatible Module Ids: Any
Feature flags: <leave empty>
Tags: <leave empty>
If deploying with a USB drive, select the option to “Copy the package to USB drive” and choose your Target drive. If installing through a network share, leave the option unselected.
Click Continue. Wait for the build to finish. Click OK to dismiss the dialog.
The package is saved under the Packages directory. For example, the P3SampleApp package would be saved in C:\P3\P3_SDK_V0.8\P3SampleApp\Packages\P3SampleApp 1.0.0.0.p3p
If the USB drive option was selected, another copy is written on the target drive.
Remember to clean up the Packages directory if you deploy multiple versions over time. Same for the USB drive, if applicable.
Follow these instructions if you chose to install your P3 application with a USB drive.
Select “Install or Update Software”.
Select “From USB Drive”.
Select the package. For example: P3SampleApp 1.0.0.0.p3p
Press the right flipper button for Yes.
Follow these instructions if you chose to install your P3 application using an SMB network share.
For example:
copy "C:\P3\P3_SDK_V0.8\P3SampleApp\Packages\P3SampleApp 1.0.0.0.p3p" c:\P3\P3Share
Select “Install or Update Software”
Select “From LAN Drive”. You will see a red message if your network share configuration is incorrect or your shared folder is empty. In that case, fix the problem and restart System Manager.
Select the package. For example: P3SampleApp 1.0.0.0.p3p
Press the right flipper button for Yes.
If the network share suddenly stops working after working for several hours or days, verify if the IP address of the computer has changed. This can happen if the lease on the address has expired and the router assigned a different address.
If you can reproduce your problem in the simulator, you can take advantage of the Unity log.
When the application is running in Unity, select the Console tab. Select the levels you want to enable on the top-right corner of the tab (info is white circle, warn is yellow triangle, error is red octogone). Each level is controlled independently, it is not a threshold.
Select a log message in the top half, and see the details of that message including the stack trace in the bottom half.
For a more global view, click on the tiny icon with 3 lines in the top-right corner (just above the red octogone) and select Open Editor Log. This opens the file %HOMEDRIVE%%HOMEPATH%\AppData\Local\Unity\Editor\Editor.log
You can open the Editor.log file directly in your favorite text tool as well.
The Editor.log is cleaned every time you start Play mode if you enabled the option “Clear on Play” in the top left corner of the Console window.
Before you can analyze your application logs produced on the P3 machine, you need to transfer them to the computer.
To transfer the logs using a USB Drive, start System Manager, select Manage Installed Software > Manage Apps. Select an application. Select Copy Log Files to USB. Press the right flipper button for Yes. This will copy the last 10 logs in the directory \P3Logs\<company>\<appid> on the USB Drive
To transfer the logs using a LAN Drive, you must have configured an SMB network share by following the instructions in the “SMB Network Share” section above, including giving read-write permissions to the login account. Start System Manager, select Manage Installed Software > Manage Apps. Select an application. Select Copy Log Files to LAN. Press the right flipper button for Yes. This will copy the last 10 logs in the directory P3Logs\<company>\<appid> in the shared folder on the computer.
For example, copying the P3SampleApp Log Files to LAN would copy 10 files named P3SA_<date>.log.gz in C:\P3\P3Share\P3Logs\Multimorphic\P3SA
To help create assets, other tools might come in handy. For example, blender for 3D meshes, gimp for images, audacity for sounds, etc…
=====================================================================================
To manage the source of your project, we recommend using git.
This is optional.
Download git for Windows at https://gitforwindows.org/ and run the installer.
Keep all default options, except I like to have the Unix-like utilities in the DOS shell.
The installer says that will override Windows find and sort, but that's not true at version 2.40.1
The utilities were last in the PATH.
Sign up for github.com
You can now sign in to the GitHub website using your email and password.
Clone a repository like P3EmptyGame
In a command prompt on Windows:
cd \P3
git clone https://github.com/clempo2/P3EmptyGame.git
You do not need to authenticate to clone public repositories.
To use the git command line with GitHub private repositories (like your own repositories), you need to
authenticate with a Personal Access Token. For security reasons, the regular GitHub password will not work.
Follow the instructions in the section: Creating a personal access token (classic)
The first time you clone a private repository with the git command line, a dialog will popup prompting
you to sign in. Select the Token tab, enter the Personal Access Token you created.
After you authenticate, the git command will continue normally.
The Personal Access Token is remembered, you do not have to enter it every time.