gungi.js 3.3.0 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,821 +1,896 @@
1
- # gungi.js
2
-
3
- [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/jwyce/gungi.js/ci.yml)](https://github.com/jwyce/gungi.js/actions)
4
- [![npm](https://img.shields.io/npm/v/gungi.js?color=blue)](https://www.npmjs.com/package/gungi.js)
5
- [![npm](https://img.shields.io/npm/dm/gungi.js)](https://www.npmjs.com/package/gungi.js)
6
-
7
- gungi.js is a TypeScript gungi library for the strategy game from the HUNTER×HUNTER manga. It implements the "official rules" trying to be as faithful as possible to what is shown in HUNTER×HUNTER.
8
- Credit to these two reddit posts from [u/magickirua](https://www.reddit.com/r/HunterXHunter/comments/uqrtct/gungi_the_official_rules) and [u/MythicalTenshi](https://www.reddit.com/r/HunterXHunter/comments/105f43g/comment/j3evkkq)
9
- which translate the rule book.
10
-
11
- gungi.js is used for move generation/validation, piece placement/movement, and endgame detection - basically everything but the AI.
12
-
13
- ## Installation
14
-
15
- Run the following command to install the most recent version of gungi.js from NPM:
16
-
17
- ```
18
- npm install gungi.js
19
- ```
20
-
21
- ## Example Code
22
-
23
- The code below plays a random game of gungi:
24
-
25
- ```ts
26
- import { ADVANCED_POSITION, Gungi } from './gungi';
27
-
28
- function clearTerminal() {
29
- process.stdout.write('\x1b[2J');
30
- process.stdout.write('\x1b[H');
31
- }
32
-
33
- function printText(text: string) {
34
- clearTerminal();
35
- process.stdout.write(text);
36
- }
37
-
38
- const gungi = new Gungi(ADVANCED_POSITION);
39
-
40
- while (!gungi.isGameOver()) {
41
- const moves = gungi.moves();
42
- const move = moves[Math.floor(Math.random() * moves.length)];
43
- gungi.move(move);
44
- printText(gungi.ascii());
45
- }
46
-
47
- console.log(gungi.fen() + '\n');
48
- console.log(gungi.pgn());
49
- ```
50
-
51
- ## API
52
-
53
- ### Constants
54
-
55
- ```js
56
- // colors
57
- const WHITE = 'w';
58
- const BLACK = 'b';
59
-
60
- // special moves
61
- export const TSUKE = '付';
62
- export const TAKE = '取';
63
- export const BETRAY = '返';
64
- export const ARATA = '新';
65
-
66
- // pieces
67
- export const MARSHAL = '帥';
68
- export const GENERAL = '大';
69
- export const LIEUTENANT_GENERAL = '中';
70
- export const MAJOR_GENERAL = '小';
71
- export const WARRIOR = '侍';
72
- export const LANCER = '槍';
73
- export const RIDER = '馬';
74
- export const SPY = '忍';
75
- export const FORTRESS = '砦';
76
- export const SOLDIER = '兵';
77
- export const CANNON = '砲';
78
- export const ARCHER = '弓';
79
- export const MUSKETEER = '筒';
80
- export const TACTICIAN = '謀';
81
-
82
- // starting positions (in FEN)
83
- export const INTRO_POSITION =
84
- '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1';
85
- export const BEGINNER_POSITION =
86
- '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1';
87
- export const INTERMEDIATE_POSITION =
88
- '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 2 wb 1';
89
- export const ADVANCED_POSITION =
90
- '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 3 wb 1';
91
-
92
- // square list
93
- export const SQUARES = ['1-1', '1-2', '1-3', ..., '7-1', '8-1', '9-1']
94
-
95
- // map of pieces to japanese names (romaji)
96
- export const CANONICAL_NAMES = { 帥: 'sui', ..., 弓: 'yumi', 筒: 'tsutsu', 謀: 'boushou' }
97
-
98
- // map of pieces to english names
99
- export const ENGLISH_NAMES = { 帥: 'marshal', ..., 弓: 'archer', 筒: 'cannon', 謀: 'tactician' }
100
-
101
- // map of pieces to fen code symbols
102
- export const FEN_CODES = { 帥: 'm', ..., 弓: 'a', 筒: 'c', 謀: 't' }
103
- ```
104
-
105
- ### Constructor: Gungi([ fen ])
106
-
107
- The Gungi() constructor takes an optional parameter which specifies the board configuration in a special variant of [Forsyth-Edwards Notation (FEN)](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation).
108
- Throws an exception if an invalid FEN string is provided. See specification differences [here](src/gungi/fen.ts).
109
-
110
- ```ts
111
- import { Gungi } from 'gungi.js'
112
-
113
- // an empty constructor defaults the starting position
114
- let gungi = new Gungi()
115
-
116
- // pass in a FEN string to load a particular position
117
- let gungi = new Gungi(
118
- 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57',
119
- )
120
-
121
- ```
122
-
123
- ### .ascii([ options ])
124
-
125
- Returns a string containing an ASCII diagram of the current position with ANSI colors. Options is an optional parameter which may contain a 'english' flag to display the pieces in English symbols.
126
-
127
- ```ts
128
- const gungi = new Gungi(BEGINNER_POSITION);
129
-
130
- // make some moves
131
- gungi.move('槍(8-5-1)(7-5-2)付');
132
- gungi.move('新馬(1-7-1)');
133
- gungi.move('新忍(8-7-2)付');
134
-
135
- gungi.ascii();
136
- // -> ' 987654321
137
- // +ーーーーーーーーー+
138
- // |・・馬中帥大・・・|1
139
- // |・馬弓・槍・弓忍・|2
140
- // |兵・砦侍兵侍砦・兵|3
141
- // |・・・・・・・・・|4
142
- // |・・・・・・・・・|5
143
- // |・・・・・・・・・|6
144
- // |兵・砦侍槍侍砦・兵|7
145
- // |・忍忍・・・弓馬・|8
146
- // |・・・大帥中・・・|9
147
- // +ーーーーーーーーー+'
148
- gungi.ascii({ english: true });
149
- // -> ' 987654321
150
- // +ーーーーーーーーー+
151
- // |・・rimg・・・|1
152
- // |・ra・n・as・|2
153
- // |d・fwdwf・d|3
154
- // |・・・・・・・・・|4
155
- // |・・・・・・・・・|5
156
- // |・・・・・・・・・|6
157
- // |D・FWNWF・D|7
158
- // |・SS・・・AR・|8
159
- // |・・・GMI・・・|9
160
- // +ーーーーーーーーー+'
161
- ```
162
-
163
- ### .board()
164
-
165
- Returns a 3D tensor representation of the current position (9x9x3 array). Empty squares are represented by `null`. Each piece includes an optional `id` property for stable tracking across moves.
166
-
167
- ```ts
168
- const gungi = new Gungi();
169
-
170
- gungi.board();
171
- // -> [[[null],
172
- // [null],
173
- // [null],
174
- // [{ square: '1-6', tier: 1, type: '中', color: 'b', id: 'b-中-1' }],
175
- // [{ square: '1-5', tier: 1, type: '帥', color: 'b', id: 'b-帥-1' }],
176
- // [{ square: '1-4', tier: 1, type: '大', color: 'b', id: 'b-大-1' }],
177
- // [null],
178
- // [null],
179
- // [null]],
180
- // [[null],
181
- // [{ square: '2-8', tier: 1, type: '忍', color: 'b', id: 'b-忍-2' }],
182
- // [null],
183
- // [null],
184
- // [{ square: '2-5', tier: 1, type: '槍', color: 'b', id: 'b-槍-1' }],
185
- // [null],
186
- // [null],
187
- // [{ square: '2-2', tier: 1, type: '忍', color: 'b', id: 'b-忍-1' }],
188
- // [null]],
189
- // [[{ square: '3-9', tier: 1, type: '兵', color: 'b', id: 'b-兵-3' }],
190
- // [null],
191
- // [{ square: '3-7', tier: 1, type: '砦', color: 'b', id: 'b-砦-2' }],
192
- // [{ square: '3-6', tier: 1, type: '侍', color: 'b', id: 'b-侍-2' }],
193
- // [{ square: '3-5', tier: 1, type: '兵', color: 'b', id: 'b-兵-2' }],
194
- // [{ square: '3-4', tier: 1, type: '侍', color: 'b', id: 'b-侍-1' }],
195
- // [{ square: '3-3', tier: 1, type: '砦', color: 'b', id: 'b-砦-1' }],
196
- // [null],
197
- // [{ square: '3-1', tier: 1, type: '兵', color: 'b', id: 'b-兵-1' }]],
198
- // [...],
199
- // [...],
200
- // [...],
201
- // [[{ square: '7-9', tier: 1, type: '兵', color: 'w' }],
202
- // [null],
203
- // [{ square: '7-7', tier: 1, type: '砦', color: 'w' }],
204
- // [{ square: '7-6', tier: 1, type: '侍', color: 'w' }],
205
- // [{ square: '7-5', tier: 1, type: '兵', color: 'w' }],
206
- // [{ square: '7-4', tier: 1, type: '侍', color: 'w' }],
207
- // [{ square: '7-3', tier: 1, type: '砦', color: 'w' }],
208
- // [null],
209
- // [{ square: '7-1', tier: 1, type: '兵', color: 'w' }]],
210
- // [[null],
211
- // [{ square: '8-8', tier: 1, type: '忍', color: 'w' }],
212
- // [null],
213
- // [null],
214
- // [{ square: '8-5', tier: 1, type: '槍', color: 'w' }],
215
- // [null],
216
- // [null],
217
- // [{ square: '8-2', tier: 1, type: '忍', color: 'w' }],
218
- // [null]],
219
- // [[null],
220
- // [null],
221
- // [null],
222
- // [{ square: '9-6', tier: 1, type: '大', color: 'w' }],
223
- // [{ square: '9-5', tier: 1, type: '帥', color: 'w' }],
224
- // [{ square: '9-4', tier: 1, type: '中', color: 'w' }],
225
- // [null],
226
- // [null],
227
- // [null]]];
228
- ```
229
-
230
- ### .captured(color)
231
-
232
- Returns a list of pieces captured. Color is an optional parameter to filter pieces by player color
233
-
234
- ```ts
235
- const gungi = new Gungi(BEGINNER_POSITION);
236
- gungi.move('新小(7-5-2)付');
237
- gungi.move('兵(3-5-1)(4-5-1)');
238
- gungi.move('新槍(7-4-2)付');
239
- gungi.move('兵(4-5-1)(5-5-1)');
240
- gungi.move('小(7-5-2)取(5-5-1)');
241
-
242
- gungi.captured('b');
243
- // -> [{ type: '兵', color: 'b', count: 1 }]
244
- ```
245
-
246
- ### .clear()
247
-
248
- Clears the board.
249
-
250
- ```ts
251
- gungi.clear();
252
- gungi.fen();
253
- // -> '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 3 wb 1' <- empty board
254
- ```
255
-
256
- ### .fen()
257
-
258
- Returns the FEN string for the current position.
259
-
260
- ```ts
261
- const gungi = new Gungi(BEGINNER_POSITION);
262
-
263
- // make some moves
264
- gungi.move('槍(8-5-1)(7-5-2)付');
265
- gungi.move('新馬(1-7-1)');
266
- gungi.move('新忍(8-7-2)付');
267
-
268
- gungi.fen();
269
- // -> '2rimg3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FW|D:N|WF1D/1S|A:S|3AR1/3GMI3 J2N2R1D1/j2n2s1d1 b 1 - 2'
270
- ```
271
-
272
- ### .get(square)
273
-
274
- Returns the tower of pieces on the square. Returns `undefined` if the square is empty.
275
-
276
- ```ts
277
- const gungi = new Gungi(BEGINNER_POSITION);
278
-
279
- gungi.move('砦(7-3-1)(7-4-2)付');
280
-
281
- gungi.get('7-4');
282
- // -> [{ square: '7-4', tier: 1, type: '侍', color: 'w', id: 'w-侍-1' }, { square: '7-4', tier: 2, type: '砦', color: 'w', id: 'w-砦-1' }]
283
- gungi.get('7-3');
284
- // -> undefined
285
- ```
286
-
287
- ### .getDraftingRights(color)
288
-
289
- Gets the drafting rights for the given color. Boolean value is return if color provided, otherwise returns an object with both colors.
290
-
291
- ```ts
292
- const gungi = new Gungi(ADVANCED_POSITION);
293
-
294
- gungi.move('新帥(7-2-1)終');
295
-
296
- gungi.getDraftingRights();
297
- // -> { w: false, b: true }
298
- gungi.getDraftingRights('b');
299
- // -> true
300
- ```
301
-
302
- ### .getTop(square)
303
-
304
- Returns the top piece of the tower on the square. Returns `undefined` if the square is empty.
305
-
306
- ```ts
307
- const gungi = new Gungi(BEGINNER_POSITION);
308
-
309
- gungi.get('7-4');
310
- // -> [{ square: '7-4', tier: 1, type: '侍', color: 'w' }]
311
- gungi.get('7-3');
312
- // -> undefined
313
- ```
314
-
315
- ### .hand(color)
316
-
317
- Returns a list of pieces in players' hand. Color is an optional parameter to filter pieces by player color. Each hand piece includes an optional `id` property for stable tracking across moves.
318
-
319
- ```ts
320
- const gungi = new Gungi(BEGINNER_POSITION);
321
-
322
- // make some moves
323
- gungi.move('槍(8-5-1)(7-5-2)付');
324
- gungi.move('新馬(1-7-1)');
325
- gungi.move('新忍(8-7-2)付');
326
-
327
- gungi.hand();
328
- // -> [
329
- // { type: '小', count: 2, color: 'w', id: 'w-小-1' },
330
- // { type: '槍', count: 2, color: 'w', id: 'w-槍-1' },
331
- // { type: '馬', count: 1, color: 'w', id: 'w-馬-1' },
332
- // { type: '兵', count: 1, color: 'w', id: 'w-兵-1' },
333
- // { type: '小', count: 2, color: 'b', id: 'b-小-1' },
334
- // { type: '槍', count: 2, color: 'b', id: 'b-槍-1' },
335
- // { type: '忍', count: 1, color: 'b', id: 'b-忍-1' },
336
- // { type: '兵', count: 1, color: 'b', id: 'b-兵-1' }
337
- // ]
338
- gungi.hand('w');
339
- // [
340
- // { type: '小', count: 2, color: 'w', id: 'w-小-1' },
341
- // { type: '槍', count: 2, color: 'w', id: 'w-槍-1' },
342
- // { type: '馬', count: 1, color: 'w', id: 'w-馬-1' },
343
- // { type: '兵', count: 1, color: 'w', id: 'w-兵-1' }
344
- // ]
345
- ```
346
-
347
- ### .history([ options ])
348
-
349
- Returns a list containing the moves of the current game. Options is an optional parameter which may contain a 'verbose' flag. See .moves() for a description of the verbose move fields.
350
- A FEN string of the position prior to the move being made is added to the verbose history output.
351
-
352
- ```ts
353
- const gungi = new Gungi(BEGINNER_POSITION);
354
- gungi.move('新小(7-5-2)付');
355
- gungi.move('兵(3-5-1)(4-5-1)');
356
- gungi.move('新槍(7-4-2)付');
357
- gungi.move('兵(4-5-1)(5-5-1)');
358
- gungi.move('小(7-5-2)取(5-5-1)');
359
-
360
- gungi.history();
361
- // -> ['砦(7-3-1)(7-4-2)付', '新小(7-5-2)付', '兵(3-5-1)(4-5-1)', '新槍(7-4-2)付', '兵(4-5-1)(5-5-1)', '小(7-5-2)取(5-5-1)']
362
-
363
- gungi.history({ verbose: true });
364
- // -->
365
- // [
366
- // {
367
- // piece: '砦',
368
- // color: 'w',
369
- // from: '7-3-1',
370
- // to: '7-4-2',
371
- // type: 'tsuke',
372
- // san: '砦(7-3-1)(7-4-2)付',
373
- // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
374
- // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWD|W:F|2D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
375
- // },
376
- // {
377
- // piece: '小',
378
- // color: 'w',
379
- // from: '',
380
- // to: '7-5-2',
381
- // type: 'arata',
382
- // san: '新小(7-5-2)付',
383
- // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
384
- // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1',
385
- // },
386
- // {
387
- // piece: '兵',
388
- // color: 'b',
389
- // from: '3-5-1',
390
- // to: '4-5-1',
391
- // type: 'route',
392
- // san: '兵(3-5-1)(4-5-1)',
393
- // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1',
394
- // after: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 w 0 - 2',
395
- // },
396
- // {
397
- // piece: '槍',
398
- // color: 'w',
399
- // from: '',
400
- // to: '7-4-2',
401
- // type: 'arata',
402
- // san: '新槍(7-4-2)付',
403
- // before: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 w 0 - 2',
404
- // after: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 2',
405
- // },
406
- // {
407
- // piece: '兵',
408
- // color: 'b',
409
- // from: '4-5-1',
410
- // to: '5-5-1',
411
- // type: 'route',
412
- // san: '兵(4-5-1)(5-5-1)',
413
- // before: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 2',
414
- // after: '3img3/1s2n2s1/d1fw1wf1d/9/4d4/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 w 0 - 3',
415
- // },
416
- // {
417
- // piece: '小',
418
- // color: 'w',
419
- // from: '7-5-2',
420
- // to: '5-5-1',
421
- // type: 'capture',
422
- // san: '小(7-5-2)取(5-5-1)',
423
- // before: '3img3/1s2n2s1/d1fw1wf1d/9/4d4/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 w 0 - 3',
424
- // after: '3img3/1s2n2s1/d1fw1wf1d/9/4J4/9/D1FWD|W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 3',
425
- // captured: [ { square: '5-5', tier: 1, type: '兵', color: 'b' } ]
426
- // }
427
- // ]
428
- ```
429
-
430
- ### .inDraft()
431
-
432
- Returns true or false if either player is still in the drafting phase.
433
-
434
- ```ts
435
- const gungi = new Gungi(ADVANCED_POSITION);
436
-
437
- gungi.move('新帥(7-2-1)終');
438
- gungi.inDraft();
439
- // -> true
440
-
441
- gungi.move('新帥(2-4-1)終');
442
- gungi.inDraft();
443
- // -> false
444
- ```
445
-
446
- ### .isFourfoldRepetition()
447
-
448
- Returns true or false if the current board position has occurred four or more times.
449
-
450
- ```ts
451
- const gungi = new Gungi(INTRO_POSITION);
452
- // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 1st time
453
- gungi.isFourfoldRepetition();
454
- // -> false
455
-
456
- gungi.move('兵(7-1-1)(6-1-1)');
457
- gungi.move('侍(3-4-1)(4-4-1)');
458
- gungi.move('兵(6-1-1)(7-1-1)');
459
- gungi.move('侍(4-4-1)(3-4-1)');
460
- // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 2nd time
461
- gungi.isFourfoldRepetition();
462
- // -> false
463
-
464
- gungi.move('兵(7-1-1)(6-1-1)');
465
- gungi.move('侍(3-4-1)(4-4-1)');
466
- gungi.move('兵(6-1-1)(7-1-1)');
467
- gungi.move('侍(4-4-1)(3-4-1)');
468
- // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 3rd time
469
- gungi.isFourfoldRepetition();
470
- // -> false
471
-
472
- gungi.move('兵(7-1-1)(6-1-1)');
473
- gungi.move('侍(3-4-1)(4-4-1)');
474
- gungi.move('兵(6-1-1)(7-1-1)');
475
- gungi.move('侍(4-4-1)(3-4-1)');
476
- // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 4th time
477
- gungi.isFourfoldRepetition();
478
- // -> true
479
- ```
480
-
481
- ### .inCheck([ color ])
482
-
483
- Returns true if the marshal of the specified color (or current turn) is under attack.
484
-
485
- ```ts
486
- const gungi = new Gungi(INTRO_POSITION);
487
- gungi.inCheck();
488
- // -> false
489
-
490
- gungi.inCheck('w');
491
- // -> false
492
- ```
493
-
494
- ### .isCheckmate()
495
-
496
- Returns true if the current player is in checkmate (in check with no legal moves).
497
-
498
- ```ts
499
- const gungi = new Gungi(ADVANCED_POSITION);
500
- gungi.isCheckmate();
501
- // -> false
502
- ```
503
-
504
- ### .isDraw()
505
-
506
- Returns true if the game has ended in a draw via stalemate or fourfold repetition.
507
-
508
- ```ts
509
- const gungi = new Gungi(ADVANCED_POSITION);
510
- gungi.isDraw();
511
- // -> false
512
- ```
513
-
514
- ### .isGameOver()
515
-
516
- Returns true if the game has ended via marshal captured, checkmate, stalemate, or fourfold repetition.
517
-
518
- ```ts
519
- const gungi = new Gungi(ADVANCED_POSITION);
520
- gungi.isGameOver();
521
- // -> false
522
-
523
- // marshal captured
524
- gungi.load(
525
- '1|g:N|2|W:N|Ad1f/7r1/1nd2Adfr/2|c:G|j2K2/6s1D/1w|W:T|6/2F4J|F:D|/i8/2|S:w||R:M|3C1 -/- b 3 - 164'
526
- );
527
- gungi.isGameOver();
528
- // -> true
529
- ```
530
-
531
- ### .isStalemate()
532
-
533
- Returns true if the current player has no legal moves but is not in check.
534
-
535
- ```ts
536
- const gungi = new Gungi(ADVANCED_POSITION);
537
- gungi.isStalemate();
538
- // -> false
539
- ```
540
-
541
- ### .load(fen)
542
-
543
- Clears the board and loads the provided FEN string. Throws an exception if the FEN is invalid.
544
-
545
- ```ts
546
- const gungi = new Gungi();
547
- gungi.load(
548
- 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57'
549
- );
550
-
551
- try {
552
- gungi.load('3img3/1ra1n1xas1/d1fwdwf1d/9/9/9/9/9 J2N2R1D1/j2n2r2d1 w 1 - 1');
553
- } catch (e) {
554
- console.log(e.message);
555
- }
556
- // -> Error: Invalid FEN: 1st field (piece positions) is invalid [expected 9 ranks, received 8]
557
- ```
558
-
559
- ### .loadPgn(pgn, fen, [ options ])
560
-
561
- Load the moves of a game stored in [Portable Game Notation](http://en.wikipedia.org/wiki/Portable_Game_Notation). `pgn` should be a string. `fen` should be the starting position of the game (defaults to `ADVANCED_POSITION`).
562
- Options is an optional object which may contain a string `newline`. PGN for gungi is slightly different from standard PGN, read more about it [here](src/gungi/pgn.ts).
563
-
564
- The `newline` is a string representation of a valid RegExp fragment and is used to process the PGN. It defaults to `\n`
565
-
566
- ```ts
567
- const gungi = new Gungi(ADVANCED_POSITION);
568
- const pgn = [
569
- '1.新帥(7-9-1)終 新帥(1-5-1) 新小(2-8-1) 新謀(1-2-1) 新馬(2-8-2)付 新大(3-4-1)終',
570
- '2.帥(7-9-1)(8-8-1) 新砦(3-2-1) 3.新謀(8-2-1) 新弓(1-8-1) 4.新弓(9-9-1) 新馬(1-3-1)',
571
- '5.新筒(9-5-1) 新弓(1-8-2)付 6.新兵(8-5-1) 新砦(3-6-1) 7.新大(8-9-1) 砦(3-6-1)(2-5-1)',
572
- '8.新小(8-9-2)付 新小(1-7-1) 9.新槍(8-2-2)付 新侍(1-2-2)付 10.新兵(9-8-1) 小(1-7-1)(2-7-1)',
573
- '11.新槍(8-6-1) 新侍(2-4-1) 12.新砦(9-9-2)付 侍(2-4-1)(3-3-1) 13.小(8-9-2)(7-8-1) 新兵(1-4-1)',
574
- ];
575
-
576
- gungi.loadPgn(pgn.join('\n'));
577
- gungi.print();
578
- // -> ' 987654321
579
- // +ーーーーーーーーー+
580
- // |・弓・・帥兵馬侍・|1
581
- // |・馬小・砦・・・・|2
582
- // |・・・・・大侍砦・|3
583
- // |・・・・・・・・・|4
584
- // |・・・・・・・・・|5
585
- // |・・・・・・・・・|6
586
- // |・小・・・・・・・|7
587
- // |大帥・槍兵・・槍・|8
588
- // |砦兵・・筒・・・・|9
589
- // +ーーーーーーーーー+'
590
- ```
591
-
592
- ### .move(move, [ options ])
593
-
594
- Makes a move on the board and returns a move object if the move was legal. The move argument can be either a string in Standard Algebraic Notation (SAN) or a move object.
595
- Throws an 'Illegal move' exception if the move was illegal.
596
-
597
- #### move() - Standard Algebraic Notation (SAN)
598
-
599
- ```ts
600
- const gungi = new Gungi(INTRO_POSITION);
601
- gungi.move('兵(7-1-1)(6-1-1)');
602
- // -> {
603
- // piece: '兵',
604
- // color: 'w',
605
- // from: '7-1-1',
606
- // to: '6-1-1',
607
- // type: 'route',
608
- // san: '兵(7-1-1)(6-1-1)',
609
- // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
610
- // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
611
- // }
612
- gungi.move('大(1-4-1)(2-10-1)');
613
- // Error: Invalid move: 大(1-4-1)(2-10-1)
614
- ```
615
-
616
- #### .move() - Object Notation
617
-
618
- A move object contains `to`, `from`, `piece`, `type` and, `captured` and `draftFinished` (only when necessary) fields.
619
-
620
- ```ts
621
- const gungi = new Gungi(INTRO_POSITION);
622
- gungi.move({ piece: SOLIDER, from: '7-1-1', to: '6-1-1', type: 'route' });
623
- // -> {
624
- // piece: '兵',
625
- // color: 'w',
626
- // from: '7-1-1',
627
- // to: '6-1-1',
628
- // type: 'route',
629
- // san: '兵(7-1-1)(6-1-1)',
630
- // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
631
- // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
632
- // }
633
- ```
634
-
635
- ### .moveNumber()
636
-
637
- Returns the current move number.
638
-
639
- ```ts
640
- gungi.load(
641
- 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57'
642
- );
643
- gungi.moveNumber();
644
- // -> 57
645
- ```
646
-
647
- ### .moves({ square?: Square, arata?: HandPiece, verbose = false} = {})
648
-
649
- Returns a list of legal moves from the current position. This function takes an optional object which can be used to generate detailed move objects or to restrict the move generator to specific squares or arata.
650
-
651
- ```ts
652
- const gungi = new Gungi(INTRO_POSITION);
653
- gungi.moves();
654
- // -> [
655
- // '兵(7-1-1)(6-1-1)', '兵(7-1-1)(8-1-1)', '砦(7-3-1)(6-3-1)',
656
- // '砦(7-3-1)(7-4-2)付', '砦(7-3-1)(7-2-1)', '砦(7-3-1)(8-4-1)',
657
- // '砦(7-3-1)(8-2-2)付', '侍(7-4-1)(6-5-1)', '侍(7-4-1)(6-4-1)',
658
- // '侍(7-4-1)(6-3-1)', '侍(7-4-1)(8-4-1)', '兵(7-5-1)(6-5-1)',
659
- // '兵(7-5-1)(8-5-2)付', '侍(7-6-1)(6-7-1)', '侍(7-6-1)(6-6-1)',
660
- // '侍(7-6-1)(6-5-1)', '侍(7-6-1)(8-6-1)', '砦(7-7-1)(6-7-1)',
661
- // '砦(7-7-1)(7-8-1)', '砦(7-7-1)(7-6-2)付', '砦(7-7-1)(8-8-2)付',
662
- // '砦(7-7-1)(8-6-1)', '兵(7-9-1)(6-9-1)', '兵(7-9-1)(8-9-1)',
663
- // '忍(8-2-1)(7-3-2)付', '忍(8-2-1)(7-1-2)付', '忍(8-2-1)(9-3-1)',
664
- // '忍(8-2-1)(9-1-1)', '槍(8-5-1)(7-6-2)付', '槍(8-5-1)(7-5-2)付',
665
- // '槍(8-5-1)(7-4-2)付', '忍(8-8-1)(7-9-2)付', '忍(8-8-1)(7-7-2)付',
666
- // '忍(8-8-1)(9-9-1)', '忍(8-8-1)(9-7-1)', '中(9-4-1)(8-5-2)付',
667
- // '中(9-4-1)(8-4-1)', '中(9-4-1)(8-3-1)', '中(9-4-1)(7-2-1)',
668
- // '中(9-4-1)(6-1-1)', '中(9-4-1)(9-3-1)', '帥(9-5-1)(8-6-1)',
669
- // '帥(9-5-1)(8-5-2)付', '帥(9-5-1)(8-4-1)', '帥(9-5-1)(9-6-2)付',
670
- // '帥(9-5-1)(9-4-2)付', '大(9-6-1)(8-7-1)', '大(9-6-1)(8-6-1)',
671
- // '大(9-6-1)(7-6-2)付', '大(9-6-1)(8-5-2)付', '大(9-6-1)(9-7-1)',
672
- // '大(9-6-1)(9-8-1)', '大(9-6-1)(9-9-1)', '新小(9-1-1)',
673
- // '新小(9-2-1)', '新小(9-3-1)', '新小(9-4-2)付',
674
- // '新小(9-6-2)付', '新小(9-7-1)', '新小(9-8-1)',
675
- // '新小(9-9-1)', '新小(8-1-1)', '新小(8-2-2)付',
676
- // '新小(8-3-1)', '新小(8-4-1)', '新小(8-5-2)付',
677
- // '新小(8-6-1)', '新小(8-7-1)', '新小(8-8-2)付',
678
- // '新小(8-9-1)', '新小(7-1-2)付', '新小(7-2-1)',
679
- // '新小(7-3-2)付', '新小(7-4-2)付', '新小(7-5-2)付',
680
- // '新小(7-6-2)付', '新小(7-7-2)付', '新小(7-8-1)',
681
- // '新小(7-9-2)付', '新槍(9-1-1)', '新槍(9-2-1)',
682
- // '新槍(9-3-1)', '新槍(9-4-2)付', '新槍(9-6-2)付',
683
- // '新槍(9-7-1)', '新槍(9-8-1)', '新槍(9-9-1)',
684
- // '新槍(8-1-1)', '新槍(8-2-2)付', '新槍(8-3-1)',
685
- // '新槍(8-4-1)', '新槍(8-5-2)付', '新槍(8-6-1)',
686
- // '新槍(8-7-1)', '新槍(8-8-2)付', '新槍(8-9-1)',
687
- // '新槍(7-1-2)付', '新槍(7-2-1)', '新槍(7-3-2)付',
688
- // '新槍(7-4-2)付',
689
- // ... 57 more items
690
- // ]
691
-
692
- gungi.moves({ square: '8-5' }); // single square move generation
693
- // -> ['槍(8-5-1)(7-6-2)付', '槍(8-5-1)(7-5-2)付', '槍(8-5-1)(7-4-2)付']
694
-
695
- gungi.moves({ arata: gungi.hand('w').at(0) }); // generate moves for arata
696
- // -> [
697
- // '新小(9-1-1)', '新小(9-2-1)',
698
- // '新小(9-3-1)', '新小(9-4-2)付',
699
- // '新小(9-6-2)付', '新小(9-7-1)',
700
- // '新小(9-8-1)', '新小(9-9-1)',
701
- // '新小(8-1-1)', '新小(8-2-2)付',
702
- // '新小(8-3-1)', '新小(8-4-1)',
703
- // '新小(8-5-2)付', '新小(8-6-1)',
704
- // '新小(8-7-1)', '新小(8-8-2)付',
705
- // '新小(8-9-1)', '新小(7-1-2)付',
706
- // '新小(7-2-1)', '新小(7-3-2)付',
707
- // '新小(7-4-2)付', '新小(7-5-2)付',
708
- // '新小(7-6-2)付', '新小(7-7-2)付',
709
- // '新小(7-8-1)', '新小(7-9-2)付'
710
- // ]
711
-
712
- gungi.moves({ verbose: true }); // return verbose moves
713
- /// -> [{ piece: '兵', color: 'w', from: '7-1-1', to: '6-1-1',
714
- /// type: 'route',
715
- /// san: '兵(7-1-1)(6-1-1)',
716
- /// before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
717
- /// after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
718
- /// # a `draftFinished` field is included when a move is ending the drafting phase
719
- /// # a `captured` field is included when a move is a capture or a betrayal
720
- /// },
721
- /// ...
722
- /// ]
723
- ```
724
-
725
- #### Move Object (e.g. when { verbose: true })
726
-
727
- The `color` field indicates the color of the moving piece (`w` or `b`).
728
-
729
- The `from` and `to` fields are from and to squares in algebraic notation.
730
-
731
- The `type` field is the type of move made (`route`, `tsuke`, `capture`, `betray`, `arata`).
732
-
733
- The `piece` and `captured` fields contain the lowercase representation of the applicable piece (mgijwnrsfdcakt). The captured field are only present when the move is a valid capture or betrayal.
734
-
735
- The `draftFinished` field is included when a move is ending the drafting phase.
736
-
737
- The `san` field is the move in Standard Algebraic Notation (SAN).
738
-
739
- The `before` and `after` keys contain the FEN of the position before and after the move.
740
-
741
- ### .pgn([ options ])
742
-
743
- Returns the game in PGN format. Options is an optional parameter which may include max width and/or a newline character settings.
744
-
745
- ```ts
746
- const gungi = new Gungi(BEGINNER_POSITION);
747
- gungi.move('槍(8-5-1)(7-5-2)付');
748
- gungi.move('新馬(1-7-1)');
749
- gungi.move('新忍(8-7-2)付');
750
-
751
- gungi.pgn({ maxWidth: 2, newlineChar: '<br />' });
752
- // -> '1. 槍(8-5-1)(7-5-2)付 新馬(1-7-1) <br />2. 新忍(8-7-2)付'
753
- ```
754
-
755
- ### .print()
756
-
757
- Print the ascii representation of the board to the console.
758
-
759
- ### .reset()
760
-
761
- Reset the board to the initial starting position.
762
-
763
- ### .turn()
764
-
765
- Returns the current side to move.
766
-
767
- ```ts
768
- gungi.load(
769
- '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1'
770
- );
771
- gungi.turn();
772
- // -> 'b'
773
- ```
774
-
775
- ### .undo()
776
-
777
- Takeback the last half-move, returning a move object if successful, otherwise null.
778
-
779
- ```ts
780
- const gungi = new Gungi(BEGINNER_POSITION);
781
-
782
- gungi.fen();
783
- // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1'
784
- gungi.move('兵(7-1-1)(6-1-1)');
785
- gungi.fen();
786
- // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/8D/D1FWDWF2/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 b 1 - 1'
787
-
788
- gungi.undo();
789
- // {
790
- // piece: '兵',
791
- // color: 'w',
792
- // from: '7-1-1',
793
- // to: '6-1-1',
794
- // type: 'route',
795
- // san: '兵(7-1-1)(6-1-1)',
796
- // before: '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1',
797
- // after: '3img3/1ra1n1as1/d1fwdwf1d/9/9/8D/D1FWDWF2/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 b 1 - 1',
798
- // }
799
-
800
- gungi.fen();
801
- // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1'
802
- gungi.undo();
803
- // -> null
804
- ```
805
-
806
- ### validateFen(fen):
807
-
808
- This static function returns a validation object specifying validity or the errors found within the FEN string.
809
-
810
- ```ts
811
- import { validateFen } from 'gungi.js';
812
-
813
- validateFen(
814
- '3img3/1s2n2s1/d1fw1wf1d/9/4J4/9/D1FWD|W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 3'
815
- );
816
- // -> { ok: true }
817
-
818
- validateFen('3img3/1ra1n1xas1/d1fwdwf1d/9/9/9/9/9/9 J2N2R1D1/j2n2r2d1 w 1 - 1');
819
- // -> { ok: false,
820
- // error: '1st field (piece positions) is invalid [invalid piece] @(2-7)' }
821
- ```
1
+ # gungi.js
2
+
3
+ [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/jwyce/gungi.js/ci.yml)](https://github.com/jwyce/gungi.js/actions)
4
+ [![npm](https://img.shields.io/npm/v/gungi.js?color=blue)](https://www.npmjs.com/package/gungi.js)
5
+ [![npm](https://img.shields.io/npm/dm/gungi.js)](https://www.npmjs.com/package/gungi.js)
6
+
7
+ gungi.js is a TypeScript gungi library for the strategy game from the HUNTER×HUNTER manga. It implements the "official rules" trying to be as faithful as possible to what is shown in HUNTER×HUNTER.
8
+ Credit to these two reddit posts from [u/magickirua](https://www.reddit.com/r/HunterXHunter/comments/uqrtct/gungi_the_official_rules) and [u/MythicalTenshi](https://www.reddit.com/r/HunterXHunter/comments/105f43g/comment/j3evkkq)
9
+ which translate the rule book.
10
+
11
+ gungi.js is used for move generation/validation, piece placement/movement, and endgame detection - basically everything but the AI.
12
+
13
+ ## Installation
14
+
15
+ Run the following command to install the most recent version of gungi.js from NPM:
16
+
17
+ ```
18
+ npm install gungi.js
19
+ ```
20
+
21
+ ## Example Code
22
+
23
+ The code below plays a random game of gungi:
24
+
25
+ ```ts
26
+ import { ADVANCED_POSITION, Gungi } from './gungi';
27
+
28
+ function clearTerminal() {
29
+ process.stdout.write('\x1b[2J');
30
+ process.stdout.write('\x1b[H');
31
+ }
32
+
33
+ function printText(text: string) {
34
+ clearTerminal();
35
+ process.stdout.write(text);
36
+ }
37
+
38
+ const gungi = new Gungi(ADVANCED_POSITION);
39
+
40
+ while (!gungi.isGameOver()) {
41
+ const moves = gungi.moves();
42
+ const move = moves[Math.floor(Math.random() * moves.length)];
43
+ gungi.move(move);
44
+ printText(gungi.ascii());
45
+ }
46
+
47
+ console.log(gungi.fen() + '\n');
48
+ console.log(gungi.pgn());
49
+ ```
50
+
51
+ ## API
52
+
53
+ ### Constants
54
+
55
+ ```js
56
+ // colors
57
+ const WHITE = 'w';
58
+ const BLACK = 'b';
59
+
60
+ // special moves
61
+ export const TSUKE = '付';
62
+ export const TAKE = '取';
63
+ export const BETRAY = '返';
64
+ export const ARATA = '新';
65
+
66
+ // pieces
67
+ export const MARSHAL = '帥';
68
+ export const GENERAL = '大';
69
+ export const LIEUTENANT_GENERAL = '中';
70
+ export const MAJOR_GENERAL = '小';
71
+ export const WARRIOR = '侍';
72
+ export const LANCER = '槍';
73
+ export const RIDER = '馬';
74
+ export const SPY = '忍';
75
+ export const FORTRESS = '砦';
76
+ export const SOLDIER = '兵';
77
+ export const CANNON = '砲';
78
+ export const ARCHER = '弓';
79
+ export const MUSKETEER = '筒';
80
+ export const TACTICIAN = '謀';
81
+
82
+ // starting positions (in FEN)
83
+ export const INTRO_POSITION =
84
+ '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1';
85
+ export const BEGINNER_POSITION =
86
+
87
+ '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1';
88
+ export const INTERMEDIATE_POSITION =
89
+ '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 2 wb 1';
90
+ export const ADVANCED_POSITION =
91
+ '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 3 wb 1';
92
+
93
+ // square list
94
+ export const SQUARES = ['1-1', '1-2', '1-3', ..., '7-1', '8-1', '9-1']
95
+
96
+ // map of pieces to japanese names (romaji)
97
+ export const CANONICAL_NAMES = { 帥: 'sui', ..., 弓: 'yumi', 筒: 'tsutsu', 謀: 'boushou' }
98
+
99
+ // map of pieces to english names
100
+ export const ENGLISH_NAMES = { 帥: 'marshal', ..., 弓: 'archer', 筒: 'cannon', 謀: 'tactician' }
101
+
102
+ // map of pieces to fen code symbols
103
+ export const FEN_CODES = { 帥: 'm', ..., 弓: 'a', 筒: 'c', 謀: 't' }
104
+ ```
105
+
106
+ ### Constructor: Gungi([ fen ])
107
+
108
+ The Gungi() constructor takes an optional parameter which specifies the board configuration in a special variant of [Forsyth-Edwards Notation (FEN)](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation).
109
+ Throws an exception if an invalid FEN string is provided. See specification differences [here](src/gungi/fen.ts).
110
+
111
+ ```ts
112
+ import { Gungi } from 'gungi.js'
113
+
114
+ // an empty constructor defaults the starting position
115
+ let gungi = new Gungi()
116
+
117
+ // pass in a FEN string to load a particular position
118
+ let gungi = new Gungi(
119
+ 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57',
120
+ )
121
+
122
+ ```
123
+
124
+ ### .ascii([ options ])
125
+
126
+ Returns a string containing an ASCII diagram of the current position with ANSI colors. Options is an optional parameter which may contain a 'english' flag to display the pieces in English symbols.
127
+
128
+ ```ts
129
+ const gungi = new Gungi(BEGINNER_POSITION);
130
+
131
+ // make some moves
132
+ gungi.move('槍(8-5-1)(7-5-2)付');
133
+ gungi.move('新馬(1-7-1)');
134
+ gungi.move('新忍(8-7-2)付');
135
+
136
+ gungi.ascii();
137
+ // -> ' 987654321
138
+ // +ーーーーーーーーー+
139
+ // |・・馬中帥大・・・|1
140
+ // |・馬弓・槍・弓忍・|2
141
+ // |兵・砦侍兵侍砦・兵|3
142
+ // |・・・・・・・・・|4
143
+ // |・・・・・・・・・|5
144
+ // |・・・・・・・・・|6
145
+ // |兵・砦侍槍侍砦・兵|7
146
+ // |・忍忍・・・弓馬・|8
147
+ // |・・・大帥中・・・|9
148
+ // +ーーーーーーーーー+'
149
+ gungi.ascii({ english: true });
150
+ // -> ' 987654321
151
+ // +ーーーーーーーーー+
152
+ // |・・rimg・・・|1
153
+ // |・ra・n・as・|2
154
+ // |d・fwdwf・d|3
155
+ // |・・・・・・・・・|4
156
+ // |・・・・・・・・・|5
157
+ // |・・・・・・・・・|6
158
+ // |D・FWNWF・D|7
159
+ // |・SS・・・AR・|8
160
+ // |・・・GMI・・・|9
161
+ // +ーーーーーーーーー+'
162
+ ```
163
+
164
+ ### .board()
165
+
166
+ Returns a 3D tensor representation of the current position (9x9x3 array). Empty squares are represented by `null`. Each piece includes an optional `id` property for stable tracking across moves.
167
+
168
+ ```ts
169
+ const gungi = new Gungi();
170
+
171
+ gungi.board();
172
+ // -> [[[null],
173
+ // [null],
174
+ // [null],
175
+ // [{ square: '1-6', tier: 1, type: '中', color: 'b', id: 'b-中-1' }],
176
+ // [{ square: '1-5', tier: 1, type: '帥', color: 'b', id: 'b-帥-1' }],
177
+ // [{ square: '1-4', tier: 1, type: '大', color: 'b', id: 'b-大-1' }],
178
+ // [null],
179
+ // [null],
180
+ // [null]],
181
+ // [[null],
182
+ // [{ square: '2-8', tier: 1, type: '忍', color: 'b', id: 'b-忍-2' }],
183
+ // [null],
184
+ // [null],
185
+ // [{ square: '2-5', tier: 1, type: '槍', color: 'b', id: 'b-槍-1' }],
186
+ // [null],
187
+ // [null],
188
+ // [{ square: '2-2', tier: 1, type: '忍', color: 'b', id: 'b-忍-1' }],
189
+ // [null]],
190
+ // [[{ square: '3-9', tier: 1, type: '兵', color: 'b', id: 'b-兵-3' }],
191
+ // [null],
192
+ // [{ square: '3-7', tier: 1, type: '砦', color: 'b', id: 'b-砦-2' }],
193
+ // [{ square: '3-6', tier: 1, type: '侍', color: 'b', id: 'b-侍-2' }],
194
+ // [{ square: '3-5', tier: 1, type: '兵', color: 'b', id: 'b-兵-2' }],
195
+ // [{ square: '3-4', tier: 1, type: '侍', color: 'b', id: 'b-侍-1' }],
196
+ // [{ square: '3-3', tier: 1, type: '砦', color: 'b', id: 'b-砦-1' }],
197
+ // [null],
198
+ // [{ square: '3-1', tier: 1, type: '兵', color: 'b', id: 'b-兵-1' }]],
199
+ // [...],
200
+ // [...],
201
+ // [...],
202
+ // [[{ square: '7-9', tier: 1, type: '兵', color: 'w' }],
203
+ // [null],
204
+ // [{ square: '7-7', tier: 1, type: '砦', color: 'w' }],
205
+ // [{ square: '7-6', tier: 1, type: '侍', color: 'w' }],
206
+ // [{ square: '7-5', tier: 1, type: '兵', color: 'w' }],
207
+ // [{ square: '7-4', tier: 1, type: '侍', color: 'w' }],
208
+ // [{ square: '7-3', tier: 1, type: '砦', color: 'w' }],
209
+ // [null],
210
+ // [{ square: '7-1', tier: 1, type: '兵', color: 'w' }]],
211
+ // [[null],
212
+ // [{ square: '8-8', tier: 1, type: '忍', color: 'w' }],
213
+ // [null],
214
+ // [null],
215
+ // [{ square: '8-5', tier: 1, type: '槍', color: 'w' }],
216
+ // [null],
217
+ // [null],
218
+ // [{ square: '8-2', tier: 1, type: '忍', color: 'w' }],
219
+ // [null]],
220
+ // [[null],
221
+ // [null],
222
+ // [null],
223
+ // [{ square: '9-6', tier: 1, type: '大', color: 'w' }],
224
+ // [{ square: '9-5', tier: 1, type: '帥', color: 'w' }],
225
+ // [{ square: '9-4', tier: 1, type: '中', color: 'w' }],
226
+ // [null],
227
+ // [null],
228
+ // [null]]];
229
+ ```
230
+
231
+ ### .captured(color)
232
+
233
+ Returns a list of pieces captured. Color is an optional parameter to filter pieces by player color
234
+
235
+ ```ts
236
+ const gungi = new Gungi(BEGINNER_POSITION);
237
+
238
+ gungi.move('新小(7-5-2)付');
239
+ gungi.move('兵(3-5-1)(4-5-1)');
240
+ gungi.move('新槍(7-4-2)付');
241
+ gungi.move('兵(4-5-1)(5-5-1)');
242
+ gungi.move('小(7-5-2)取(5-5-1)');
243
+
244
+ gungi.captured('b');
245
+ // -> [{ type: '兵', color: 'b', count: 1 }]
246
+ ```
247
+
248
+ ### .clear()
249
+
250
+ Clears the board.
251
+
252
+ ```ts
253
+ gungi.clear();
254
+ gungi.fen();
255
+ // -> '9/9/9/9/9/9/9/9/9 M1G1I1J2W2N3R2S2F2D4C1A2K1T1/m1g1i1j2w2n3r2s2f2d4c1a2k1t1 w 3 wb 1' <- empty board
256
+ ```
257
+
258
+ ### .fen()
259
+
260
+ Returns the FEN string for the current position.
261
+
262
+ ```ts
263
+ const gungi = new Gungi(BEGINNER_POSITION);
264
+
265
+ // make some moves
266
+ gungi.move('槍(8-5-1)(7-5-2)付');
267
+ gungi.move('新馬(1-7-1)');
268
+ gungi.move('新忍(8-7-2)付');
269
+
270
+ gungi.fen();
271
+ // -> '2rimg3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FW|D:N|WF1D/1S|A:S|3AR1/3GMI3 J2N2R1D1/j2n2s1d1 b 1 - 2'
272
+ ```
273
+
274
+ ### .get(square)
275
+
276
+ Returns the tower of pieces on the square. Returns `undefined` if the square is empty.
277
+
278
+ ```ts
279
+ const gungi = new Gungi(BEGINNER_POSITION);
280
+
281
+ gungi.move('砦(7-3-1)(7-4-2)付');
282
+
283
+ gungi.get('7-4');
284
+ // -> [{ square: '7-4', tier: 1, type: '侍', color: 'w', id: 'w-侍-1' }, { square: '7-4', tier: 2, type: '砦', color: 'w', id: 'w-砦-1' }]
285
+ gungi.get('7-3');
286
+ // -> undefined
287
+ ```
288
+
289
+ ### .getDraftingRights(color)
290
+
291
+ Gets the drafting rights for the given color. Boolean value is return if color provided, otherwise returns an object with both colors.
292
+
293
+ ```ts
294
+ const gungi = new Gungi(ADVANCED_POSITION);
295
+
296
+ gungi.move('新帥(7-2-1)終');
297
+
298
+ gungi.getDraftingRights();
299
+ // -> { w: false, b: true }
300
+ gungi.getDraftingRights('b');
301
+ // -> true
302
+ ```
303
+
304
+ ### .getTop(square)
305
+
306
+ Returns the top piece of the tower on the square. Returns `undefined` if the square is empty.
307
+
308
+ ```ts
309
+ const gungi = new Gungi(BEGINNER_POSITION);
310
+
311
+ gungi.get('7-4');
312
+ // -> [{ square: '7-4', tier: 1, type: '侍', color: 'w' }]
313
+ gungi.get('7-3');
314
+ // -> undefined
315
+ ```
316
+
317
+ ### .hand(color)
318
+
319
+ Returns a list of pieces in players' hand. Color is an optional parameter to filter pieces by player color. Each hand piece includes an optional `id` property for stable tracking across moves.
320
+
321
+ ```ts
322
+ const gungi = new Gungi(BEGINNER_POSITION);
323
+
324
+ // make some moves
325
+ gungi.move('槍(8-5-1)(7-5-2)付');
326
+ gungi.move('新馬(1-7-1)');
327
+ gungi.move('新忍(8-7-2)付');
328
+
329
+ gungi.hand();
330
+ // -> [
331
+ // { type: '小', count: 2, color: 'w', id: 'w-小-1' },
332
+ // { type: '槍', count: 2, color: 'w', id: 'w-槍-1' },
333
+ // { type: '馬', count: 1, color: 'w', id: 'w-馬-1' },
334
+ // { type: '兵', count: 1, color: 'w', id: 'w-兵-1' },
335
+ // { type: '小', count: 2, color: 'b', id: 'b-小-1' },
336
+ // { type: '槍', count: 2, color: 'b', id: 'b-槍-1' },
337
+ // { type: '忍', count: 1, color: 'b', id: 'b-忍-1' },
338
+ // { type: '兵', count: 1, color: 'b', id: 'b-兵-1' }
339
+ // ]
340
+ gungi.hand('w');
341
+ // [
342
+ // { type: '小', count: 2, color: 'w', id: 'w-小-1' },
343
+ // { type: '槍', count: 2, color: 'w', id: 'w-槍-1' },
344
+ // { type: '馬', count: 1, color: 'w', id: 'w-馬-1' },
345
+ // { type: '兵', count: 1, color: 'w', id: 'w-兵-1' }
346
+ // ]
347
+ ```
348
+
349
+ ### .history([ options ])
350
+
351
+ Returns a list containing the moves of the current game. Options is an optional parameter which may contain a 'verbose' flag. See .moves() for a description of the verbose move fields.
352
+ A FEN string of the position prior to the move being made is added to the verbose history output.
353
+
354
+ ```ts
355
+ const gungi = new Gungi(BEGINNER_POSITION);
356
+
357
+ gungi.move('新小(7-5-2)付');
358
+ gungi.move('兵(3-5-1)(4-5-1)');
359
+ gungi.move('新槍(7-4-2)付');
360
+ gungi.move('兵(4-5-1)(5-5-1)');
361
+ gungi.move('小(7-5-2)取(5-5-1)');
362
+
363
+ gungi.history();
364
+ // -> ['砦(7-3-1)(7-4-2)付', '新小(7-5-2)付', '兵(3-5-1)(4-5-1)', '新槍(7-4-2)付', '兵(4-5-1)(5-5-1)', '小(7-5-2)取(5-5-1)']
365
+
366
+ gungi.history({ verbose: true });
367
+ // -->
368
+ // [
369
+ // {
370
+ // piece: '砦',
371
+ // color: 'w',
372
+ // from: '7-3-1',
373
+ // to: '7-4-2',
374
+ // type: 'tsuke',
375
+ // san: '砦(7-3-1)(7-4-2)付',
376
+ // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
377
+ // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWD|W:F|2D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
378
+ // },
379
+ // {
380
+ // piece: '小',
381
+ // color: 'w',
382
+ // from: '',
383
+ // to: '7-5-2',
384
+ // type: 'arata',
385
+ // san: '新小(7-5-2)付',
386
+ // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
387
+ // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1',
388
+ // },
389
+ // {
390
+ // piece: '兵',
391
+ // color: 'b',
392
+ // from: '3-5-1',
393
+ // to: '4-5-1',
394
+ // type: 'route',
395
+ // san: '兵(3-5-1)(4-5-1)',
396
+ // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1',
397
+ // after: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 w 0 - 2',
398
+ // },
399
+ // {
400
+ // piece: '槍',
401
+ // color: 'w',
402
+ // from: '',
403
+ // to: '7-4-2',
404
+ // type: 'arata',
405
+ // san: '新槍(7-4-2)付',
406
+ // before: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 w 0 - 2',
407
+ // after: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 2',
408
+ // },
409
+ // {
410
+ // piece: '兵',
411
+ // color: 'b',
412
+ // from: '4-5-1',
413
+ // to: '5-5-1',
414
+ // type: 'route',
415
+ // san: '兵(4-5-1)(5-5-1)',
416
+ // before: '3img3/1s2n2s1/d1fw1wf1d/4d4/9/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 2',
417
+ // after: '3img3/1s2n2s1/d1fw1wf1d/9/4d4/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 w 0 - 3',
418
+ // },
419
+ // {
420
+ // piece: '小',
421
+ // color: 'w',
422
+ // from: '7-5-2',
423
+ // to: '5-5-1',
424
+ // type: 'capture',
425
+ // san: '小(7-5-2)取(5-5-1)',
426
+ // before: '3img3/1s2n2s1/d1fw1wf1d/9/4d4/9/D1FW|D:J||W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 w 0 - 3',
427
+ // after: '3img3/1s2n2s1/d1fw1wf1d/9/4J4/9/D1FWD|W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 3',
428
+ // captured: [ { square: '5-5', tier: 1, type: '兵', color: 'b' } ]
429
+ // }
430
+ // ]
431
+ ```
432
+
433
+ ### .inDraft()
434
+
435
+ Returns true or false if either player is still in the drafting phase.
436
+
437
+ ```ts
438
+ const gungi = new Gungi(ADVANCED_POSITION);
439
+
440
+ gungi.move('新帥(7-2-1)終');
441
+ gungi.inDraft();
442
+ // -> true
443
+
444
+ gungi.move('新帥(2-4-1)終');
445
+ gungi.inDraft();
446
+ // -> false
447
+ ```
448
+
449
+ ### .isFourfoldRepetition()
450
+
451
+ Returns true or false if the current board position has occurred four or more times.
452
+
453
+ ```ts
454
+ const gungi = new Gungi(INTRO_POSITION);
455
+ // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 1st time
456
+ gungi.isFourfoldRepetition();
457
+ // -> false
458
+
459
+ gungi.move('兵(7-1-1)(6-1-1)');
460
+ gungi.move('侍(3-4-1)(4-4-1)');
461
+ gungi.move('兵(6-1-1)(7-1-1)');
462
+ gungi.move('侍(4-4-1)(3-4-1)');
463
+ // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 2nd time
464
+ gungi.isFourfoldRepetition();
465
+ // -> false
466
+
467
+ gungi.move('兵(7-1-1)(6-1-1)');
468
+ gungi.move('侍(3-4-1)(4-4-1)');
469
+ gungi.move('兵(6-1-1)(7-1-1)');
470
+ gungi.move('侍(4-4-1)(3-4-1)');
471
+ // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 3rd time
472
+ gungi.isFourfoldRepetition();
473
+ // -> false
474
+
475
+ gungi.move('兵(7-1-1)(6-1-1)');
476
+ gungi.move('侍(3-4-1)(4-4-1)');
477
+ gungi.move('兵(6-1-1)(7-1-1)');
478
+ gungi.move('侍(4-4-1)(3-4-1)');
479
+ // 3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1 occurs 4th time
480
+ gungi.isFourfoldRepetition();
481
+ // -> true
482
+ ```
483
+
484
+ ### .inCheck([ color ])
485
+
486
+ Returns true if the marshal of the specified color (or current turn) is under attack.
487
+
488
+ ```ts
489
+ const gungi = new Gungi(INTRO_POSITION);
490
+ gungi.inCheck();
491
+ // -> false
492
+
493
+ gungi.inCheck('w');
494
+ // -> false
495
+ ```
496
+
497
+ ### .isCheckmate()
498
+
499
+ Returns true if the current player is in checkmate (in check with no legal moves).
500
+
501
+ ```ts
502
+ const gungi = new Gungi(ADVANCED_POSITION);
503
+ gungi.isCheckmate();
504
+ // -> false
505
+ ```
506
+
507
+ ### .isDraw()
508
+
509
+ Returns true if the game has ended in a draw via stalemate or fourfold repetition.
510
+
511
+ ```ts
512
+ const gungi = new Gungi(ADVANCED_POSITION);
513
+ gungi.isDraw();
514
+ // -> false
515
+ ```
516
+
517
+ ### .isGameOver()
518
+
519
+ Returns true if the game has ended via marshal captured, checkmate, stalemate, or fourfold repetition.
520
+
521
+ ```ts
522
+ const gungi = new Gungi(ADVANCED_POSITION);
523
+ gungi.isGameOver();
524
+ // -> false
525
+
526
+ // marshal captured
527
+ gungi.load(
528
+ '1|g:N|2|W:N|Ad1f/7r1/1nd2Adfr/2|c:G|j2K2/6s1D/1w|W:T|6/2F4J|F:D|/i8/2|S:w||R:M|3C1 -/- b 3 - 164'
529
+ );
530
+ gungi.isGameOver();
531
+ // -> true
532
+ ```
533
+
534
+ ### .isStalemate()
535
+
536
+ Returns true if the current player has no legal moves but is not in check.
537
+
538
+ ```ts
539
+ const gungi = new Gungi(ADVANCED_POSITION);
540
+ gungi.isStalemate();
541
+ // -> false
542
+ ```
543
+
544
+ ### .load(fen)
545
+
546
+ Clears the board and loads the provided FEN string. Throws an exception if the FEN is invalid.
547
+
548
+ ```ts
549
+ const gungi = new Gungi();
550
+ gungi.load(
551
+ 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57'
552
+ );
553
+
554
+ try {
555
+ gungi.load('3img3/1ra1n1xas1/d1fwdwf1d/9/9/9/9/9 J2N2R1D1/j2n2r2d1 w 1 - 1');
556
+ } catch (e) {
557
+ console.log(e.message);
558
+ }
559
+ // -> Error: Invalid FEN: 1st field (piece positions) is invalid [expected 9 ranks, received 8]
560
+ ```
561
+
562
+ ### .loadPgn(pgn, fen, [ options ])
563
+
564
+ Load the moves of a game stored in [Portable Game Notation](http://en.wikipedia.org/wiki/Portable_Game_Notation). `pgn` should be a string. `fen` should be the starting position of the game (defaults to `ADVANCED_POSITION`).
565
+ Options is an optional object which may contain a string `newline`. PGN for gungi is slightly different from standard PGN, read more about it [here](src/gungi/pgn.ts).
566
+
567
+ The `newline` is a string representation of a valid RegExp fragment and is used to process the PGN. It defaults to `\n`
568
+
569
+ ```ts
570
+ const gungi = new Gungi(ADVANCED_POSITION);
571
+ const pgn = [
572
+ '1.新帥(7-9-1)終 新帥(1-5-1) 新小(2-8-1) 新謀(1-2-1) 新馬(2-8-2)付 新大(3-4-1)終',
573
+ '2.帥(7-9-1)(8-8-1) 新砦(3-2-1) 3.新謀(8-2-1) 新弓(1-8-1) 4.新弓(9-9-1) 新馬(1-3-1)',
574
+ '5.新筒(9-5-1) 新弓(1-8-2)付 6.新兵(8-5-1) 新砦(3-6-1) 7.新大(8-9-1) 砦(3-6-1)(2-5-1)',
575
+ '8.新小(8-9-2)付 新小(1-7-1) 9.新槍(8-2-2)付 新侍(1-2-2)付 10.新兵(9-8-1) 小(1-7-1)(2-7-1)',
576
+ '11.新槍(8-6-1) 新侍(2-4-1) 12.新砦(9-9-2)付 侍(2-4-1)(3-3-1) 13.小(8-9-2)(7-8-1) 新兵(1-4-1)',
577
+ ];
578
+
579
+ gungi.loadPgn(pgn.join('\n'));
580
+ gungi.print();
581
+ // -> ' 987654321
582
+ // +ーーーーーーーーー+
583
+ // |・弓・・帥兵馬侍・|1
584
+ // |・馬小・砦・・・・|2
585
+ // |・・・・・大侍砦・|3
586
+ // |・・・・・・・・・|4
587
+ // |・・・・・・・・・|5
588
+ // |・・・・・・・・・|6
589
+ // |・小・・・・・・・|7
590
+ // |大帥・槍兵・・槍・|8
591
+ // |砦兵・・筒・・・・|9
592
+ // +ーーーーーーーーー+'
593
+ ```
594
+
595
+ ### .move(move, [ options ])
596
+
597
+ Makes a move on the board and returns a move object if the move was legal. The move argument can be either a string in Standard Algebraic Notation (SAN) or a move object.
598
+ Throws an 'Illegal move' exception if the move was illegal.
599
+
600
+ #### move() - Standard Algebraic Notation (SAN)
601
+
602
+ ```ts
603
+ const gungi = new Gungi(INTRO_POSITION);
604
+ gungi.move('兵(7-1-1)(6-1-1)');
605
+ // -> {
606
+ // piece: '兵',
607
+ // color: 'w',
608
+ // from: '7-1-1',
609
+ // to: '6-1-1',
610
+ // type: 'route',
611
+ // san: '兵(7-1-1)(6-1-1)',
612
+ // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
613
+ // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
614
+ // }
615
+ gungi.move('大(1-4-1)(2-10-1)');
616
+ // Error: Invalid move: 大(1-4-1)(2-10-1)
617
+ ```
618
+
619
+ #### .move() - Object Notation
620
+
621
+ A move object contains `to`, `from`, `piece`, `type` and, `captured` and `draftFinished` (only when necessary) fields.
622
+
623
+ ```ts
624
+ const gungi = new Gungi(INTRO_POSITION);
625
+ gungi.move({ piece: SOLIDER, from: '7-1-1', to: '6-1-1', type: 'route' });
626
+ // -> {
627
+ // piece: '兵',
628
+ // color: 'w',
629
+ // from: '7-1-1',
630
+ // to: '6-1-1',
631
+ // type: 'route',
632
+ // san: '兵(7-1-1)(6-1-1)',
633
+ // before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
634
+ // after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
635
+ // }
636
+ ```
637
+
638
+ ### .moveNumber()
639
+
640
+ Returns the current move number.
641
+
642
+ ```ts
643
+ gungi.load(
644
+ 'd1f1|r:d||r:j|j|k:a:c||g:s|/3|w:s|2|n:w|2/f8/3n2d1m/2i4W1/3dN1tR1/4D2R1/ASJ2|C:a|1A1/|I:F:W|F1SGMT1|K:J| -/- w 3 - 57'
645
+ );
646
+ gungi.moveNumber();
647
+ // -> 57
648
+ ```
649
+
650
+ ### .moves({ square?: Square, arata?: HandPiece, verbose = false} = {})
651
+
652
+ Returns a list of legal moves from the current position. This function takes an optional object which can be used to generate detailed move objects or to restrict the move generator to specific squares or arata.
653
+
654
+ ```ts
655
+ const gungi = new Gungi(INTRO_POSITION);
656
+ gungi.moves();
657
+ // -> [
658
+ // '兵(7-1-1)(6-1-1)', '兵(7-1-1)(8-1-1)', '砦(7-3-1)(6-3-1)',
659
+ // '砦(7-3-1)(7-4-2)付', '砦(7-3-1)(7-2-1)', '砦(7-3-1)(8-4-1)',
660
+ // '砦(7-3-1)(8-2-2)付', '侍(7-4-1)(6-5-1)', '侍(7-4-1)(6-4-1)',
661
+ // '侍(7-4-1)(6-3-1)', '侍(7-4-1)(8-4-1)', '兵(7-5-1)(6-5-1)',
662
+ // '兵(7-5-1)(8-5-2)付', '侍(7-6-1)(6-7-1)', '侍(7-6-1)(6-6-1)',
663
+ // '侍(7-6-1)(6-5-1)', '侍(7-6-1)(8-6-1)', '砦(7-7-1)(6-7-1)',
664
+ // '砦(7-7-1)(7-8-1)', '砦(7-7-1)(7-6-2)付', '砦(7-7-1)(8-8-2)付',
665
+ // '砦(7-7-1)(8-6-1)', '兵(7-9-1)(6-9-1)', '兵(7-9-1)(8-9-1)',
666
+ // '忍(8-2-1)(7-3-2)付', '忍(8-2-1)(7-1-2)付', '忍(8-2-1)(9-3-1)',
667
+ // '忍(8-2-1)(9-1-1)', '槍(8-5-1)(7-6-2)付', '槍(8-5-1)(7-5-2)付',
668
+ // '槍(8-5-1)(7-4-2)付', '忍(8-8-1)(7-9-2)付', '忍(8-8-1)(7-7-2)付',
669
+ // '忍(8-8-1)(9-9-1)', '忍(8-8-1)(9-7-1)', '中(9-4-1)(8-5-2)付',
670
+ // '中(9-4-1)(8-4-1)', '中(9-4-1)(8-3-1)', '中(9-4-1)(7-2-1)',
671
+ // '中(9-4-1)(6-1-1)', '中(9-4-1)(9-3-1)', '帥(9-5-1)(8-6-1)',
672
+ // '帥(9-5-1)(8-5-2)付', '帥(9-5-1)(8-4-1)', '帥(9-5-1)(9-6-2)付',
673
+ // '帥(9-5-1)(9-4-2)付', '大(9-6-1)(8-7-1)', '大(9-6-1)(8-6-1)',
674
+ // '大(9-6-1)(7-6-2)付', '大(9-6-1)(8-5-2)付', '大(9-6-1)(9-7-1)',
675
+ // '大(9-6-1)(9-8-1)', '大(9-6-1)(9-9-1)', '新小(9-1-1)',
676
+ // '新小(9-2-1)', '新小(9-3-1)', '新小(9-4-2)付',
677
+ // '新小(9-6-2)付', '新小(9-7-1)', '新小(9-8-1)',
678
+ // '新小(9-9-1)', '新小(8-1-1)', '新小(8-2-2)付',
679
+ // '新小(8-3-1)', '新小(8-4-1)', '新小(8-5-2)付',
680
+ // '新小(8-6-1)', '新小(8-7-1)', '新小(8-8-2)付',
681
+ // '新小(8-9-1)', '新小(7-1-2)付', '新小(7-2-1)',
682
+ // '新小(7-3-2)付', '新小(7-4-2)付', '新小(7-5-2)付',
683
+ // '新小(7-6-2)付', '新小(7-7-2)付', '新小(7-8-1)',
684
+ // '新小(7-9-2)付', '新槍(9-1-1)', '新槍(9-2-1)',
685
+ // '新槍(9-3-1)', '新槍(9-4-2)付', '新槍(9-6-2)付',
686
+ // '新槍(9-7-1)', '新槍(9-8-1)', '新槍(9-9-1)',
687
+ // '新槍(8-1-1)', '新槍(8-2-2)付', '新槍(8-3-1)',
688
+ // '新槍(8-4-1)', '新槍(8-5-2)付', '新槍(8-6-1)',
689
+ // '新槍(8-7-1)', '新槍(8-8-2)付', '新槍(8-9-1)',
690
+ // '新槍(7-1-2)付', '新槍(7-2-1)', '新槍(7-3-2)付',
691
+ // '新槍(7-4-2)付',
692
+ // ... 57 more items
693
+ // ]
694
+
695
+ gungi.moves({ square: '8-5' }); // single square move generation
696
+ // -> ['槍(8-5-1)(7-6-2)付', '槍(8-5-1)(7-5-2)付', '槍(8-5-1)(7-4-2)付']
697
+
698
+ gungi.moves({ arata: gungi.hand('w').at(0) }); // generate moves for arata
699
+ // -> [
700
+ // '新小(9-1-1)', '新小(9-2-1)',
701
+ // '新小(9-3-1)', '新小(9-4-2)付',
702
+ // '新小(9-6-2)付', '新小(9-7-1)',
703
+ // '新小(9-8-1)', '新小(9-9-1)',
704
+ // '新小(8-1-1)', '新小(8-2-2)付',
705
+ // '新小(8-3-1)', '新小(8-4-1)',
706
+ // '新小(8-5-2)付', '新小(8-6-1)',
707
+ // '新小(8-7-1)', '新小(8-8-2)付',
708
+ // '新小(8-9-1)', '新小(7-1-2)付',
709
+ // '新小(7-2-1)', '新小(7-3-2)付',
710
+ // '新小(7-4-2)付', '新小(7-5-2)付',
711
+ // '新小(7-6-2)付', '新小(7-7-2)付',
712
+ // '新小(7-8-1)', '新小(7-9-2)付'
713
+ // ]
714
+
715
+ gungi.moves({ verbose: true }); // return verbose moves
716
+ /// -> [{ piece: '兵', color: 'w', from: '7-1-1', to: '6-1-1',
717
+ /// type: 'route',
718
+ /// san: '兵(7-1-1)(6-1-1)',
719
+ /// before: '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FWDWF1D/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 1',
720
+ /// after: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
721
+ /// # a `draftFinished` field is included when a move is ending the drafting phase
722
+ /// # a `captured` field is included when a move is a capture or a betrayal
723
+ /// },
724
+ /// ...
725
+ /// ]
726
+ ```
727
+
728
+ #### Move Object (e.g. when { verbose: true })
729
+
730
+ The `color` field indicates the color of the moving piece (`w` or `b`).
731
+
732
+ The `from` and `to` fields are from and to squares in algebraic notation.
733
+
734
+ The `type` field is the type of move made (`route`, `tsuke`, `capture`, `betray`, `arata`).
735
+
736
+ The `piece` and `captured` fields contain the lowercase representation of the applicable piece (mgijwnrsfdcakt). The captured field are only present when the move is a valid capture or betrayal.
737
+
738
+ The `draftFinished` field is included when a move is ending the drafting phase.
739
+
740
+ The `san` field is the move in Standard Algebraic Notation (SAN).
741
+
742
+ The `before` and `after` keys contain the FEN of the position before and after the move.
743
+
744
+ ### .pgn([ options ])
745
+
746
+ Returns the game in PGN format. Options is an optional parameter which may include max width, newline character, and whether to include comments.
747
+
748
+ ```ts
749
+ const gungi = new Gungi(BEGINNER_POSITION);
750
+ gungi.move('槍(8-5-1)(7-5-2)付');
751
+ gungi.move('新馬(1-7-1)');
752
+ gungi.move('新忍(8-7-2)付');
753
+
754
+ gungi.pgn({ maxWidth: 2, newline: '<br />' });
755
+ // -> '1. 槍(8-5-1)(7-5-2)付 新馬(1-7-1) <br />2. 新忍(8-7-2)付'
756
+
757
+ gungi.undo();
758
+ gungi.undo();
759
+ gungi.setComment('Great opening move!');
760
+ gungi.move('新馬(1-7-1)');
761
+ gungi.move('新忍(8-7-2)付');
762
+ gungi.pgn({ withComments: true });
763
+ // -> '1. 槍(8-5-1)(7-5-2)付 {Great opening move!} 新馬(1-7-1) 2. 新忍(8-7-2)付'
764
+ ```
765
+
766
+ ### .setComment(comment)
767
+
768
+ Sets a comment for the current position.
769
+
770
+ ```ts
771
+ const gungi = new Gungi(INTRO_POSITION);
772
+ gungi.move('兵(7-1-1)(6-1-1)');
773
+ gungi.setComment('Advancing the soldier');
774
+ gungi.move('侍(3-4-1)(4-4-1)');
775
+ gungi.setComment('Counter move');
776
+ ```
777
+
778
+ ### .getComment()
779
+
780
+ Gets the comment for the current position. Returns `undefined` if no comment exists.
781
+
782
+ ```ts
783
+ gungi.getComment();
784
+ // -> 'Counter move'
785
+ ```
786
+
787
+ ### .removeComment()
788
+
789
+ Removes and returns the comment for the current position. Returns `undefined` if no comment exists.
790
+
791
+ ```ts
792
+ gungi.removeComment();
793
+ // -> 'Counter move'
794
+ gungi.getComment();
795
+ // -> undefined
796
+ ```
797
+
798
+ ### .getComments()
799
+
800
+ Returns an array of all comments with their corresponding FEN positions.
801
+
802
+ ```ts
803
+ gungi.getComments();
804
+ // -> [
805
+ // {
806
+ // fen: '3img3/1s2n2s1/d1fwdwf1d/9/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 b 0 - 1',
807
+ // comment: 'Advancing the soldier'
808
+ // },
809
+ // {
810
+ // fen: '3img3/1s2n2s1/d1fw1wf1d/5w3/9/8D/D1FWDWF2/1S2N2S1/3GMI3 J2N2R2D1/j2n2r2d1 w 0 - 2',
811
+ // comment: 'Counter move'
812
+ // }
813
+ // ]
814
+ ```
815
+
816
+ ### .removeComments()
817
+
818
+ Removes and returns all comments.
819
+
820
+ ```ts
821
+ gungi.removeComments();
822
+ // -> [
823
+ // { fen: '...', comment: 'Advancing the soldier' },
824
+ // { fen: '...', comment: 'Counter move' }
825
+ // ]
826
+ gungi.getComments();
827
+ // -> []
828
+ ```
829
+
830
+ ### .print()
831
+
832
+ Print the ascii representation of the board to the console.
833
+
834
+ ### .reset()
835
+
836
+ Reset the board to the initial starting position.
837
+
838
+ ### .turn()
839
+
840
+ Returns the current side to move.
841
+
842
+ ```ts
843
+ gungi.load(
844
+ '3img3/1s2n2s1/d1fwdwf1d/9/9/9/D1FW|D:J|WF1D/1S2N2S1/3GMI3 J1N2R2D1/j2n2r2d1 b 0 - 1'
845
+ );
846
+ gungi.turn();
847
+ // -> 'b'
848
+ ```
849
+
850
+ ### .undo()
851
+
852
+ Takeback the last half-move, returning a move object if successful, otherwise null.
853
+
854
+ ```ts
855
+ const gungi = new Gungi(BEGINNER_POSITION);
856
+
857
+ gungi.fen();
858
+ // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1'
859
+ gungi.move('兵(7-1-1)(6-1-1)');
860
+ gungi.fen();
861
+ // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/8D/D1FWDWF2/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 b 1 - 1'
862
+
863
+ gungi.undo();
864
+ // {
865
+ // piece: '兵',
866
+ // color: 'w',
867
+ // from: '7-1-1',
868
+ // to: '6-1-1',
869
+ // type: 'route',
870
+ // san: '兵(7-1-1)(6-1-1)',
871
+ // before: '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1',
872
+ // after: '3img3/1ra1n1as1/d1fwdwf1d/9/9/8D/D1FWDWF2/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 b 1 - 1',
873
+ // }
874
+
875
+ gungi.fen();
876
+ // -> '3img3/1ra1n1as1/d1fwdwf1d/9/9/9/D1FWDWF1D/1SA1N1AR1/3GMI3 J2N2S1R1D1/j2n2s1r1d1 w 1 - 1'
877
+ gungi.undo();
878
+ // -> null
879
+ ```
880
+
881
+ ### validateFen(fen):
882
+
883
+ This static function returns a validation object specifying validity or the errors found within the FEN string.
884
+
885
+ ```ts
886
+ import { validateFen } from 'gungi.js';
887
+
888
+ validateFen(
889
+ '3img3/1s2n2s1/d1fw1wf1d/9/4J4/9/D1FWD|W:N|F1D/1S2N2S1/3GMI3 J1N1R2D1/j2n2r2d1 b 0 - 3'
890
+ );
891
+ // -> { ok: true }
892
+
893
+ validateFen('3img3/1ra1n1xas1/d1fwdwf1d/9/9/9/9/9/9 J2N2R1D1/j2n2r2d1 w 1 - 1');
894
+ // -> { ok: false,
895
+ // error: '1st field (piece positions) is invalid [invalid piece] @(2-7)' }
896
+ ```