@pkmn/view

A library for building Pokémon Showdown client UIs.

Installation

$ npm install @pkmn/view

Usage

@pkmn/view provides a collection of view-related helpers and wrappers which build upon the @pkmn/client and extend its functionality in ways which are relevant for building client UIs.

This package is expected to grow in scope, as several primitives have yet to be completed (eg. AnimatedBattle). Currently, this package offers a LogFormatter for pretty-printing the battle protocol and a ChoiceBuilder helper to make it easier for humans to construct responses.

LogFormatter

The LogFormatter pretty-prints Pokémon Showdown's battle protocol, either as marked up text with formatText or as HTML with formatHTML (see the UI integration test for an example of the latter). The formatter can format the text from the perspective of either side.

import {Dex} from '@pkmn/dex';
import {Generations} from ('@pkmn/data');
import {Battle} from '@pkmn/client';
import {Protocol} from '@pkmn/protocol';
import {LogFormatter} from '@pkmn/view';

const gens = new Generations(Dex);
const battle = new Battle(gens);
const formatter = new LogFormatter(0 /* perspective */, battle);

for (const {args, kwArgs} of Protocol.parse(chunk)) {
  // NOTE: must come *before* handler
  const formatted = formatter.formatText(args, kwArgs);
  if (formatted) process.stdout.write(formatted);
  battle.add(args, kwArgs);
}

If the LogFormatter is used by itself the output will be less detailed and accurated, as it requires certain state about the battle that is more difficult to track to comphrensively display the proper output for every scenario. Instead, the LogFormatter can be instantiated with a 'Tracker' which handles tracking the full state, though importantly, LogFormatter operates on the pre-updated state and thus must be called before its Tracker. @pkmn/client's Battle is currently the only implementation of a Tracker.

The format-battle script productionizes the above example and is comparable to the parse test script in smogon/pokemon-showdown-client, though will return subtly different results because format-battle leverages the full Battle state (via the second parameter to the LogFormatter).

ChoiceBuilder

ChoiceBuilder provides a way to incrementally build up a player's response to a |request| message. It provides features such as filling in pass choices where appropriate, guarding against the wrong sorts of responses being issued for the various request types, and convenience helpers to allow for flexibly specifying choices in a more human-friendly and intuitive way.

import {ChoiceBuilder} from '@pkmn/view';
import {Protocol} from '@pkmn/protocol';

const request = Protocol.parseRequest(str);
const builder = new ChoiceBuilder(request);
builder.addChoice('switch Gengar');
builder.addChoice('move 3');
const choice = builder.toString();

Browser

The recommended way of using @pkmn/view in a web browser is to configure your bundler (Webpack, Rollup, Parcel, etc) to minimize it and package it with the rest of your application.

License

This package is distributed under the terms of the MIT License. Substantial amounts of the code have been derived from the portions of the Pokémon Showdown client which are distributed under the MIT License.