Skip to main content

Martial Codex teaches the martial arts over the web. We designed and built an experience to do it.

Mobile (Google's "Material") Design, WebGL Engine Development

Martial Codex came to thoughtbot with the goal of preserving and documenting a number of martial arts. The team cared deeply about their practice and felt they deserved to be captured in time – unfortunately, most masters in the modern day rarely get the chance to teach dedicated life-long apprentices, which in turn endangers the future of the art.

The Martial Codex team wanted to preserve the arts by involving the masters from the start, giving them an opportunity to leave a legacy for their heirs or to open their innovations to the wider martial community.

Their goal of preserving the arts would be done through motion capture, 3D animation, and a smart implementation to deliver it. Motion capture allowed the team to capture numerous styles and techniques in the purest form possible. The team that came to us had a very clear understanding of what they wanted to build.

We kicked off the project with a week long design sprint. We were able to understand their goals, what we were building, and our challenges quickly and cut the sprint short to begin building. Our two biggest challenges were that non-technical users might feel uncomfortable with the technology and the technology itself.

Overall, the design aspect of the project was straightforward. Our biggest fear was users being deterred by extra plugins and headaches that technology could impose. This led us to a short user flow, dropping users into the application within two clicks, nothing more.

A further challenge was convincing users that Martial Codex wasn't trying to replace the instructor/student relationship, and that technology can help the learning process without subverting it. Much of the site was designed to highlight that the project is a part of and allied with martial culture.

At the time the project started, WebGL still had very limited adoption. Safari did not support it, Internet Explorer was very spotty, and Firefox had bugs. However, we felt that the lack of compatibility was worth it. The only other solution, Unity, required a plugin which most people would not already have installed – the stop to install a plugin phase would affect our flow, and with it our conversion rates.

Building a WebGL rendering engine was not a small task. We knew from the start that we would only support a very small number of browsers, but that allowed us to take advantage of the more recent features of JavaScript and HTML. The engine itself had four major iterations, as we tried various frameworks.

Ultimately, we had issues with all of them, and the final app was written in raw WebGL. While this meant more code to maintain and longer development cycles, it also meant we could more heavily optimize performance for our specific use case. As we began work on the mobile versions, we also found most of the engine could be used directly without significant rewrites.

Content Html

The final requirement of the project was a way for the clients to script the scenes and develop the lessons on top of the animation data. For instance, a 4 second animation file can be up to 5 minutes as a narrated lesson. A GUI overlay on top of the engine would have been the "best" solution, but we knew that was out of scope for MVP. Since the scripts would be written by semi-technical users, we decided that a simple scripting language to describe the interactions would be sufficient. The final implementation was a Ruby DSL which emitted a simple JSON structure reminiscent of byte code.

Martial Codex remains one of the most cutting edge engineering projects with unique design requirements that we've have the opportunity to work on. Check out final site (and run the demo) at Martial Codex.

“ This has been a great collaboration from start to finish... not just professional but outright inspired work in the face of an untested and demanding concept. The Martial Codex project has a powerful, flexible, efficient, and stable application as the result, and we wouldn't hesitate to enthusiastically recommend thoughtbot to others in the future. ”
Nathan Barbey, Co-founder, Martial Codex


Our best work gets done when we can work face-to-face with you. Chat with a designer or developer at one of our studios near you.

Let’s make something great together

Adding value to billions of lines of code every day

Code Climate contacted us about collaborating on product development, and as longtime users of their service, we were excited to take the opportunity to work on their product.

See how we helped make your codebase better
This site uses cookies. Learn more by visiting our privacy policy.