📝

Word Puzzle

gameType: "word-puzzle"

Wordle-style word puzzles with configurable word length and guess limits. With 399+ Wordle clones on the market, this is one of the most in-demand content types. GameplayGen selects target words from a real dictionary, scores them by letter frequency for difficulty, and generates sample guess sequences with full letter-state feedback (correct / present / absent).

Interactive Example

📝 Word Puzzle

Wordle-style word guessing with letter feedback

difficulty: 0.45solved in 4/6
S
T
A
R
E
R
A
I
S
E
A
R
E
N
A
C
R
A
N
E
Correct position Wrong position Not in word

Word Length

5

Max Guesses

6

Dictionary

2,315 words

Difficulty

0.45

Try it

await pf.generate({
  gameType: "word-puzzle",
  params: { wordLength: 5, maxGuesses: 6 },
  count: 30,
  difficulty: { target: 0.50, curve: "ascending" }
})

API Parameters

ParamTypeRequiredDefaultDescription
wordLengthnumberYes5Target word length. Range 4–7. The embedded dictionary covers these lengths.
maxGuessesnumberYes6Maximum number of guesses the player gets. Fewer guesses = harder puzzle.
includeSampleGuessesbooleanNotrueWhether to include a sample guess sequence in the output. Useful for demos and testing. Set to false for production to save bandwidth.

Difficulty Scoring

Difficulty is based on letter commonality. Words with common letters (E, T, A, O, I, N, S, R, H, L, D) are easier — players are more likely to guess them. Words with uncommon letters or unusual patterns are harder.

The generator sorts the dictionary by a "commonality score" (proportion of unique letters that are common). Higher difficulty targets pick from words with lower commonality scores — meaning more unusual, harder-to-guess words.

Content Output

ParamTypeRequiredDefaultDescription
targetWordstring——The target word the player must guess.
wordLengthnumber——Length of the target word.
maxGuessesnumber——Maximum guesses allowed.
sampleGuessesGuessResult[]——Array of sample guesses, each with: { word: string, feedback: LetterFeedback[] }. Each LetterFeedback has letter, state ("correct" | "present" | "absent"), and position.
dictionarySizenumber——Total valid words for this word length (for reference/display).

Letter Feedback Schema

typescript
interface LetterFeedback {
  letter: string;       // The guessed letter
  state: LetterState;   // "correct" | "present" | "absent"
  position: number;     // 0-indexed position in the word
}

interface GuessResult {
  word: string;                // The guessed word
  feedback: LetterFeedback[];  // Feedback for each letter
}

// Feedback rules (same as Wordle):
// "correct" → letter is in the correct position
// "present" → letter is in the word but wrong position
// "absent"  → letter is not in the word

Example Request

bash
curl -X POST https://api.gameplaygen.com/generate \
  -H "Authorization: Bearer gg_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameType": "word-puzzle",
    "params": {
      "wordLength": 5,
      "maxGuesses": 6,
      "includeSampleGuesses": true
    },
    "count": 30,
    "difficulty": {
      "min": 0.3,
      "max": 0.8,
      "curve": "ascending"
    }
  }'

Example Response

json
{
  "content": [
    {
      "id": "gg_wp5x8n3",
      "gameType": "word-puzzle",
      "content": {
        "targetWord": "crane",
        "wordLength": 5,
        "maxGuesses": 6,
        "sampleGuesses": [
          {
            "word": "stare",
            "feedback": [
              { "letter": "s", "state": "absent", "position": 0 },
              { "letter": "t", "state": "absent", "position": 1 },
              { "letter": "a", "state": "present", "position": 2 },
              { "letter": "r", "state": "present", "position": 3 },
              { "letter": "e", "state": "correct", "position": 4 }
            ]
          },
          {
            "word": "crane",
            "feedback": [
              { "letter": "c", "state": "correct", "position": 0 },
              { "letter": "r", "state": "correct", "position": 1 },
              { "letter": "a", "state": "correct", "position": 2 },
              { "letter": "n", "state": "correct", "position": 3 },
              { "letter": "e", "state": "correct", "position": 4 }
            ]
          }
        ],
        "dictionarySize": 2315
      },
      "metrics": {
        "verified": true,
        "difficulty": 0.32,
        "balance": 0.95,
        "novelty": 1.0,
        "quality": 0.89,
        "notes": ["Common word, high letter frequency score"]
      }
    }
  ],
  "requested": 30,
  "delivered": 30,
  "stats": {
    "totalCandidates": 30,
    "totalValidated": 30,
    "totalRejected": 0,
    "totalTime": 180,
    "avgDifficulty": 0.55,
    "difficultyRange": [0.32, 0.78]
  }
}

Tips for Game Integration

  • ▸Daily puzzles: Use a date-based seed (e.g., seed: 20250715) to give all players the same daily word. Combine with count: 1 for the classic daily format.
  • ▸Difficulty packs: Use ascending curves to create level packs that start easy and get progressively harder. Players love the sense of increasing challenge.
  • ▸Client-side validation: The feedback algorithm is deterministic — you can validate guesses client-side using the same rules (correct → present → absent). Only store the target word server-side.
  • ▸Keyboard highlighting: Track letter states across all guesses to color the on-screen keyboard. The sampleGuesses array shows how state accumulates.
  • ▸Variable word lengths: Support 4–7 letter modes for variety. Shorter words are harder to guess (fewer positions to eliminate), longer words have more permutations.