Mjx

Mjx is a Japanese Mahjong (riichi Mahjong) simulator. Mjx works as a game server as Mjai, a popular Mahjong simulator, to evaluate Mahjong AIs but have additional features:

Fast (100x faster than Mjai)
Exact Tenhou compatibility (Mjx is validated with numerous Tenhou game logs)
Gym-like API
Easy distributed computing (available for large-scale RL and evaluation thanks to gRPC)
Mjai compatible (mjx_mjai_translater)
Beautiful visualization

Quick start

Google colab

Install

$ pip install mjx

Requirements. Mjx supports Python3.7 or later in Linux and macOS Intel (10.15 or later). Currently Windows and macOS Apple Silicon are NOT supported. Contributions for supporting Windows and macOS Apple Silicon are more than welcome!

Example

import mjx
from mjx.agents import RandomAgent

agent = RandomAgent()
env = mjx.MjxEnv()
obs_dict = env.reset()
while not env.done():
  actions = {player_id: agent.act(obs)
    for player_id, obs in obs_dict.items()}
  obs_dict = env.step(actions)
returns = env.rewards()

Sever Usage

Server	Client
import random import mjx class RandomAgent(mjx.Agent): def __init__(self): super().__init__() # When you use neural network models # you may want to infer actions by batch def act_batch(self, observations): return [random.choice(obs.legal_actions()) for obs in observations] agent = RandomAgent() # act_batch is called instead of act agent.serve("127.0.0.1:8080", batch_size=8)	import mjx host="127.0.0.1:8080" mjx.run( {f"player_{i}": host for i in range(4)}, num_games=1000, num_parallels=16 )

Server

Client

import random
import mjx

class RandomAgent(mjx.Agent):
  def __init__(self):
    super().__init__()

  # When you use neural network models
  # you may want to infer actions by batch
  def act_batch(self, observations):
    return [random.choice(obs.legal_actions()) 
            for obs in observations]


agent = RandomAgent()
# act_batch is called instead of act
agent.serve("127.0.0.1:8080", batch_size=8)

import mjx

host="127.0.0.1:8080"

mjx.run(
  {f"player_{i}": host for i in range(4)},
  num_games=1000,
  num_parallels=16
)

This sever usage uses gRPC. Thus, actually any programming language is available to develop your own Mahjong AI. For Python, we provide a convinent wrapper mjx.Agent.serve().

Notes

Mjx is still under active development. APIs might change without notice before v1.0. Especially,

Default behavior of env.rewards(reward_type)and env.done(done_type)
Protobuf schema
Feature extraction APIs (currently, provided by Observation.to_features())

How to develop

We recommend you to develop Mjx inside a container. Easiest way is open this repository from VsCode. Feel free to mention to @sotetsuk if you have any questions.

License

MIT

matsurih/mjx