From OniGalore
Jump to navigation Jump to search
Zukai logo.png
Zukai Multiplayer
Developer: Iritscen
Currently at v0.061
released 2015.08.01
Change log Bug reporting
Forum thread

Zukai is the most recent attempt at multiplayer for Oni. Zukai is in an alpha-like stage of development for macOS until it reaches v0.1, at which point it will be ported to Windows, and development will continue on both platforms. It currently comes in the form of a bundle called Daodan.plugin and an Oni level plugin called level0_Zukai with supplemental resources.

Zukai is a Japanese word connected to the ancient art of puppetry and puppet theater (bunraku). Its usage in this project is based on the expression Ningyō Zukai ("Puppet Master") in Ghost in the Shell, though translations of the word zukai alone range from "messenger" to "operator" to "familiar spirit" to "trainer". The icon for the project is based on the kanji for another word for puppetry, ayatsuri (操り).


See the official release forum thread for download links.


Note: You must start with a vanilla Oni installation. Zukai does not yet support mods or the Anniversary Edition.
  1. Disable the scripting for the level you want to play in. A simple way to do this for all levels is to rename the IGMD folder to "~IGMD".
  2. Make sure that you have version 1.2 (or later) of the Oni game app (see forum thread for download link).
  3. Place Daodan.plugin in the Oni installation folder at the same level as the game app.
  4. Place the level0_Zukai.dat/raw/sep files in GameDataFolder.
  5. Add the line "bind m to mp_menu" to key_config.txt, or use whatever key is more convenient for you than 'm'. Create another binding for "mp_score" to be able to display the scoreboard during a match. Additional optional bindings are listed below.


Look for the Zukai icon in the bottom-left before proceeding.
Use the arrow keys to navigate the menu.
  1. Decide what level you are going to play. Obtain the IP address of the player that will be hosting. If you get tired of dealing with IP addresses, players can sign up for a No-IP domain and provide that URL to players instead, e.g. joe-oni-fan.ddns.net.
  2. Launch Oni. Look for the Zukai icon on the Main Menu (pictured, left) to make sure that the plugin is active.
  3. Choose "Load Game" and load the level you are going to play (you can double-click the title or any save point, since scripting is disabled).
  4. Press your mp_menu key to bring up the Multiplayer Menu (pictured, right).
  5. Just follow the menus. The option "Join Iritscen's game" will not work unless I have let you know that I am hosting a game. If you are joining a game, and the other player has registered a No-IP domain or has some other URL which leads to his computer, you can type this into the "Host IP address/URL" field instead of an IP address. Also note that you can copy text from another window such as your chat client and paste it into the address field in the Multiplayer Menu.
  6. Because multiplayer cannot be paused, you are not allowed to access the Main Menu while playing Zukai. To quit playing, bring up the Multiplayer Menu and choose "Exit game", or double-tap the Escape key (if the host quits, this will end the match for everyone).

Hosting tips

  • If you want to be able to host games, and not just join other people's games, make sure that you have forwarded port 2680 (UDP) to your computer's LAN (private) IP address in your router's settings. See this port forwarding guide for help.
  • Until there is metaserver support (i.e., a matchmaking lobby), you will need to arrange matches with other players using a third-party program like an instant messenger or a chat room (our community IRC channel is #Oni at euIRC.net, and an invite to our Discord server, which is currently more active, is here).
  • Some hosts are plagued by the macOS dialog that says "Do you want the application 'Oni' to accept incoming network connections?" each time someone tries to join their game. To turn this off, you should add this Oni application to your Firewall exceptions (System Preferences > Security & Privacy > Firewall > Firewall Options... > '+' button). Sometimes this will not work, in which case you need to open Terminal and use this command, remembering to supply the correct path to your Oni application (your administrator password will be requested):
sudo codesign --force --deep --verbose --continue --file-list - --sign - /path/to/Oni.app/
This performs ad-hoc code-signing, which takes the place of an official developer certificate. If successful, you will see output like this:
/Applications/Oni/Oni.app: signed bundle with Mach-O thin (i386) [com.godgames.oni]

If it does not work, try the command several more times; it often doesn't seem to work on the first try. However, even if the signing is successful, you still have to tell macOS that the app is allowed to accept incoming connections, which means that you will get the dialog again the next time that you host. Once you click that "Allow" button one more time, macOS should remember that this "signed" copy of Oni can accept connections.

Useful websites and programs

  • You might want to make use of What's My IP to get your Internet IP address (there are plenty of other websites that do this too).
  • No-IP.com can be used to set up a domain for someone who wants to host frequently, allowing the easier exchange of host addresses with joiners than giving out the host's IP address.
  • If the performance of an Internet game seems poor, look at the ping between you and other players. Zukai displays ping on the scoreboard when you press the mp_score button (see "Bindable actions" section), but if you want more rigorous measurement of the connection between yourself and another player, bring up Spotlight in macOS and start typing "Network Utility". When the Utility appears, open it and use the Ping tab to test the connection between you and them. The most important numbers in the final statistics, once pinging is done, are the packet loss, which should be 0-1%, the average ping ("round-trip avg", the third-to-last number), and jitter ("stddev", the last number), which should be less than 25% of the average ping.
  • To record video footage of a match, see Capturing game footage. The recommended free method is using either OBS Studio or QuickTime Player for video, and capturing the game audio with either Soundflower or iShowU Audio Capture. The recommended commercial programs are ScreenFlow and iShowU, which capture both audio and video.

Known bugs and limitations

At the moment, Zukai is still rough, but the following problem areas will be the main focus of future updates until they are all corrected.

  • You can only play as Konoko.
  • No text chat.
  • No proper matches or modes yet. All players can run around and attack each other, but there is no time limit or kill limit.
  • No respawning or "intelligent" spawn points. Until respawning is introduced, players will not die. All players spawn around the host, who spawns at whatever Bungie West set as the default spawn point for Konoko. Because there is no death, the closest thing to a score is the total damage done, displayed with the mp_score button (see "Bindable actions" section), but this number is not synchronized between players yet, so each player will probably see a higher score for himself than what others will see for him.
  • Weapons and some other things are not synchronized yet, and may cause gameplay to go out-of-sync (oos). You will have to start a new match to correct this.
  • IPv6 is not supported yet, so if you have a v6-only IP address, you can't play. Please let me know if this affects you.
  • Gameplay is currently very vulnerable to packet loss when a new player is joining; sometimes the match will "hang" because of this. To reduce packet loss, use a wired connection to your router/modem, not wireless. Packet loss resilience will come in an update fairly soon.
  • Sometimes the wrong map name (level name) is given on the scoreboard.

Bindable actions

In addition to the standard actions that you have always been able to bind using key_config.txt, here is a list of actions added by the Zukai plugin for use in multiplayer mode.

All players

Both hosts and clients can use these actions:

This brings up the Multiplayer Menu when you are in-game, allowing you to host, join, or exit a game.
Holding this key down displays the scoreboard, along with match time and player ping.
Coming soon!
mp_graph_toggle, mp_graph_cycle
To turn on, and cycle through, graphs that display information about the state of the multiplayer game. The network graph shows the size of incoming and outgoing traffic, and the timing graph shows how much time the multiplayer code is taking to execute in each frame.

Hosts only

These actions may only be available during this early phase of Zukai's development. They allow the host to change network settings for all players during a match, in order to see how performance is affected. You probably will want to talk to me before using them, but here they are:

latency_toggle, latency_up, latency_down
To turn on and adjust simulated latency. This feature is intended for use in matches with negligible real latency, e.g., LAN/loopback games, to reproduce the feel of an Internet game. If used in an Internet game, this will add additional latency on top of whatever natural latency already exists.
jitter_toggle, jitter_up, jitter_down
Simulated jitter (variation in latency) is automatically turned on when simulated latency is turned on, but you can use these actions to turn it off (to get flat simulated latency) or to alter the amount of jitter.
pkt_rate_up, pkt_rate_down
You can send gameplay data more or less frequently using these keys. The rate is measured as a delay in ticks, so raising the rate leads to sending data less frequently.
state_rate_up, state_rate_down
State events are communications between the client and the host which determine a client's correct position. As above, higher numbers mean less frequent events.
pos_tol_up, pos_tol_down
Not currently used. The "position tolerance" is how many world units a client's position can differ between his avatar on the host and his avatar on his own machine before his position is corrected. Higher numbers will mean that games are permitted to go further out of sync. Lower numbers will cause more frequent adjustments in position for clients. A world unit is four inches, so a position tolerance of 3 means "one foot".
This is for developer use and does not have any effect in the MP builds which I am distributing.


When Zukai first runs, it creates a blank zukai_settings.txt file in the same folder. You can change certain settings from their defaults by assigning values to them with this syntax:


Here are the settings currently supported:

Setting name Values Default Description
lock_these_settings yes/no no No effect. Planned for use with an upcoming feature.
log_all_cli_output yes/no no For diagnosing issues with automatic log uploading; turning this on will dump messages from the upload process into the system log (Console.app).
log_everything_for ... ... Turns on extra logging detail. Only intended for use by the developer.
offer_loopback_network_type yes/no no Offer the choice of "Loopback" on the "Network type selection" screen. Allows testing of MP on a single machine by running multiple copies of Oni.
send_log_after_match yes/no yes You can turn off the automatic log upload that occurs after a match, but please don't do that unless it is causing issues.