Skip to the content

Kotoba documentation

Kotoba API: every export

Every export of every entry point, each with its own page. This page keeps the addresses the old one-page reference had.

@johnmorrisdotca/kotoba/children-filter

checkTextfunction

Check a name or other short text a child has typed.

isCleanfunction

Say whether a name or short text passes the children's filter.

@johnmorrisdotca/kotoba/words-en

EN_WORDSconstant

THE ENGLISH WORDS FOR GOMOJI.

@johnmorrisdotca/kotoba/words-fr

FR_WORDSconstant

THE FRENCH WORDS FOR GOMOJI.

@johnmorrisdotca/kotoba/words-de

DE_WORDSconstant

THE GERMAN WORDS FOR GOMOJI.

@johnmorrisdotca/kotoba/pop-answers

POP_ANSWERSconstant

Pop-culture answer words, grouped by word length.

@johnmorrisdotca/kotoba/pop-guesses

POP_GUESSESconstant

POP GOMOJI'S DICTIONARY GUESSES AT THREE AND SEVEN LETTERS, the lengths Gomoji's English lists do not have.

@johnmorrisdotca/kotoba/kana-3

@johnmorrisdotca/kotoba/kana-4

@johnmorrisdotca/kotoba/kana-5

@johnmorrisdotca/kotoba/idioms-ja

@johnmorrisdotca/kotoba/shiritori-ja

@johnmorrisdotca/kotoba/proverbs-ja

@johnmorrisdotca/kotoba/yojijukugo-ja

@johnmorrisdotca/kotoba/cli

cliLanguagefunction

The language the command line speaks: --lang, or the environment's, or the system's; Japanese for ja…, English for anything else.

CliTiertype

Which words of a list: the easy answers, every answer, or every word that may be guessed.

CliWordstype

The lists the command line reads: the alphabet languages and Japanese kana.

runClifunction

Run the command line.

@johnmorrisdotca/kotoba/meanings-en-4

@johnmorrisdotca/kotoba/meanings-en-5

@johnmorrisdotca/kotoba/meanings-en-6

@johnmorrisdotca/kotoba/meanings-en

englishMeaningfunction

What an English word means, in a short line, or null for a word with no meaning to show: one WordNet has no entry for, a word of the other languages, or one left out because it is not for children.

PackedMeaningstype

The meanings of one length of word as a data file holds them: the release it was made from, and a row to a line, each the word, a tab and the line.

readMeaningsfunction

Reads a stored list of meanings into a map from word to line.

@johnmorrisdotca/kotoba/load

LoadedWordListtype

A list read into words: the easy answers inside the answers inside the words that may be guessed.

loadWordListfunction

One list of one size read into words, or null for a size the language has no list of.

WORD_LIST_SIZESconstant

The sizes each list comes in: four to six letters, or three to five kana.

WordListNametype

The languages that have a list to load: English, French, German, and Japanese kana.

@johnmorrisdotca/kotoba/play

KOTOBA_PLAY_CSSconstant

The game's stylesheet: added to the page once, as a <style> with the id kotoba-play-style.

KotobaNewGametype

What newGame may change: the choices about the word, and nothing about the look.

KotobaPlayOptionstype

What a round is dealt from, and how the game looks and behaves.

mountKotobafunction

Put a word game into container, and deal the first round.

@johnmorrisdotca/kotoba/element

defineGamefunction

Defines the default game or a subclass under a custom tag.

KotobaElementOptionstype

Host data, appearance overrides, loading and callbacks; attributes override round choices.

KotobaGameclass

A word game with scoped keyboard handling, reflected choices and UTC daily play.

@johnmorrisdotca/kotoba/element/define

defineGamefunction

Defines the default game or a subclass under a custom tag.

KotobaElementOptionstype

Host data, appearance overrides, loading and callbacks; attributes override round choices.

KotobaGameclass

A word game with scoped keyboard handling, reflected choices and UTC daily play.

@johnmorrisdotca/kotoba

ALPHABETSconstant

The letters each alphabet game's words are written in, as a character class.

changeWordGamefunction

The last kana typed made small or large again (つ and っ), or given the next mark (は, ば, ぱ).

cycleMarkfunction

゛゜: a kana's mark, round in turn — は → ば → ぱ → は, か → が → か, う → ゔ → う; a kana with no marked form stays.

dailyIndexfunction

Which of count words a day gets, from 0 to count - 1.

dailyWordfunction

The word of a day: the same for everybody who asks about the same day of the same list.

dayKeyfunction

The calendar day a moment falls on, as YYYY-MM-DD: in UTC unless an IANA time zone such as Asia/Tokyo is named.

DayKeytype

A day's name: four digits of year, two of month and two of day, such as 2026-10-01.

dayNumberfunction

How many days after 1970-01-01 a day is, counting the calendar and nothing else: a day has no hours here.

decodeGuessesfunction

Guesses run together, size letters each, read back as a list; null for anything else.

decodeHiddenfunction

A hidden word read back, in lower case, or null for one that is not size letters of the language's alphabet.

encodeHiddenfunction

A hidden word as it is written down for a puzzle: in capitals.

eraseWordGamefunction

The last thing typed taken back: romaji not yet a kana first, then the last kana or letter.

finishRomajifunction

At Enter: what was typed, with a last "n" read as ん and any other unfinished sound dropped.

foundBonusfunction

Finding the word: 10 for every place of every guess the board gives, so it grows with the board.

GomojiLanguagetype

The alphabet games: English, French, German, and the pop-culture English list.

guessMarksfunction

How each place of a guess did against the hidden word.

Idiomtype

One set phrase.

IdiomKindtype

Whose judgement put a phrase on the list: "idiom" is JMdict's own, an entry it marks idiomatic; "expression" is this package's rule, for set phrases JMdict files as plain expressions (鼻が高い, "proud").

isDayKeyfunction

Whether the text is a real calendar date written YYYY-MM-DD, from the year 0000 to 9999.

isKanaGamefunction

Whether a round is played in kana.

isSmallfunction

Whether this kana is one of the supported small forms.

KANA_COLUMNconstant

WHAT A KANA WORD SCORES, won or lost, on English's scale (wordScore) so the two boards read alike.

KANA_SIZESconstant

The lengths the kana lists come in.

kanaBasefunction

A kana without its size or its mark: ぱ → は, っ → つ, ゔ → う.

kanaFamilyfunction

The gojūon row a kana belongs to, by its base, or null for ー and anything that is no kana.

kanaFoundfunction

Found: every place plain green — the right kana, the right size, the right mark.

KanaMarktype

HOW A KANA GUESS IS COLOURED, by John's rules for Gomoji in kana (2026-09-25; the table is in docs/plans/other/WORD-04-kana.md):

KanaMarkedtype

One kana guess position with its native match and size/voicing differences.

kanaScorefunction

Score kana guesses using exact, elsewhere and same-family matches plus found and speed bonuses.

KanaScoretype

The word-score components with the additional same-kana-family column component.

kanaTonefunction

Which mark a kana carries: none, ゛ or ゜.

KEYBOARD_ROWSconstant

THE PHYSICAL KEYBOARD DRAWN UNDER A GOMOJI GRID, by language: QWERTY for English, AZERTY for French (the same 26 plain letters English's keys carry, arranged the way a French keyboard is), and QWERTZ for German, with Ä, Ö and Ü carried as keys of their own — German's letters, not English's plus a fold.

keyMarksfunction

The best mark each letter has earned across the guesses, for colouring a keyboard: a hit beats near beats miss.

kotobaLanguagefunction

The language a person asked for, by en or ja or a tag that begins with one: English for anything else.

kotobaSayfunction

A string with its braces filled in from values; a brace with no value is left as it is.

Languagetype

The languages Kotoba speaks.

LetterMarktype

How a guessed letter did: in its place, in the word elsewhere, or not in it.

LONG_BARconstant

The long-vowel bar, a character of its own.

markGuessfunction

Each letter of a guess marked against the hidden word, counting a letter only as often as the word holds it.

markKanaGuessfunction

A guess coloured against the word, place by place.

Packedtype

A kana list as its entry point exports it: the JMdict release, an alphabet of kana and one character a kana for each, and the three lists written in those characters.

PackedIdiomstype

The idiom list as it is stored: one row a phrase, the three flags as 0 or 1.

PackedSayingstype

The proverb and four-character compound lists as they are stored: one row an entry, the two flags as 0 or 1.

PlaceMarktype

One place of a marked guess: how it did, and for kana whether its size or mark is wrong.

playShiritorifunction

Judges one word against the readings played so far.

readIdiomsfunction

Reads the stored idiom list into plain rows.

readRomajifunction

What has been typed, as kana, and what is still being typed.

readSayingsfunction

Reads a stored list of proverbs or four-character compounds into plain rows.

readShiritoriWordsfunction

Reads the stored shiritori list into plain rows, commonest first.

readWordListsfunction

One length of a list read into words, or null for a length the list does not have.

Sayingtype

One proverb or four-character compound.

searchIdiomsfunction

The phrases that hold a piece of text in their written form, their reading or any of their meanings, ignoring case.

searchSayingsfunction

The proverbs or compounds that hold a piece of text in their written form, their reading or any of their meanings, ignoring case.

shiritoriChoicesfunction

The words of a pool that could be played next and do not lose, in the pool's own order.

shiritoriDistractorScorefunction

How tempting a word that does not continue the chain is, for a game offering wrong answers: 0 for a word that does continue, or holds no kana; 1 for any other; more for one that shares the vowel, or that ends where the chain stands.

shiritoriHeadKeyfunction

The kana a reading starts on, or null when it holds none.

ShiritoriRefusaltype

Why a word was refused: it starts on the wrong kana, holds no kana, or was said already.

shiritoriTailKeyfunction

The kana the next word must start on, or null when the word ends the chain: it ends in ん, or holds no kana.

startWordGamefunction

A new round: nothing guessed, nothing typed.

submitWordGamefunction

The guess being typed sent in, now being the time in milliseconds.

toggleSizefunction

小: a kana made small, or large again (つ ⇄ っ); one with no small form stays as it is.

typeWordGamefunction

One key typed, now being the time in milliseconds (the first key starts the clock).

unpackfunction

A packed kana list read into its words, size kana each.

VERSIONconstant

The package's version.

WORD_SCOREconstant

WHAT A GOMOJI WORD SCORES, won or lost.

WordDatatype

An alphabet list as its entry point exports it: for each length, the easy answers, all the answers and every word that may be guessed, each a run of words between spaces.

wordGameKeysfunction

The keys a round accepts, by the character each types: the letters of the language's keyboard, and for kana the letters of romaji and the long-vowel bar.

WordGameLanguagetype

The languages a round is played in: the alphabet ones and Japanese kana.

WordGameRefusaltype

Why a guess was not taken: it was too short, or the list does not have the word.

WordGameStatustype

How a round stands: still being played, found, or out of guesses.

WordGameSubmittype

A guess sent in: the round after it, and why the guess was not taken, if it was not.

WordListLanguagetype

The languages with a dictionary of their own: English, French and German.

WordListstype

One length of an alphabet list, read: the easy answers, every answer, and the words that may be guessed.

wordScorefunction

rows is how many guesses the puzzle gives (guessesFor), which sets every weight.

WordScoretype

The placed-letter, elsewhere-letter, found-word and speed components and their total.