GameService.Sdk.WordSearch 1.0.0

Word Search SDK

GameService.Sdk.WordSearch is a lightweight, high-performance C# library for generating Word Search puzzles. It is built on .NET Standard 2.1, making it compatible with Unity, Blazor, ASP.NET Core, and Console Applications.

🚀 Features

• Flexible Grid Sizes: Supports 7x7, 9x9, 15x15, or any custom size.
• Smart Placement: Handles Horizontal, Vertical, and Diagonal (forward & backward) placement.
• Overlap Support: Automatically allows words to share characters (e.g., "APPLE" and "PEAR" sharing 'P').
• Safety Filters: Built-in interface to block inappropriate words via AI or blocklists.
• Dependency Free: No external dependencies, ensuring a small footprint.

📦 Installation

Since you have downloaded the package, ensure it is referenced in your project:

<PackageReference Include="GameService.Sdk.WordSearch" Version="1.0.0" />

⚡ Quick Start

Here is the minimal code to generate a 9x9 puzzle.

using WordSearch.Core.Generator;
using WordSearch.Core.Models;

// 1. Define your words
var words = new List<string> { "UNITY", "CSHARP", "CODE", "GAME" };

// 2. Initialize the Generator
var generator = new PuzzleGenerator();

// 3. Generate a 9x9 Board
// Params: (WordList, GridSize, TargetWordCount)
PuzzleBoard board = generator.Generate(words, 9, words.Count);

// 4. Access the Grid (2D Array)
char letter = board.Grid[0, 0]; 

// 5. Access the Solutions (Where the words are hidden)
foreach (var solution in board.Solutions)
{
    Console.WriteLine($"Word: {solution.Word} starts at {solution.StartPos.Row},{solution.StartPos.Col}");
}

📖 Detailed Usage

1. Understanding the PuzzleBoard Object

The Generate method returns a PuzzleBoard object containing two key properties:

• Grid: A char[,] array representing the letters. Grid[row, col].
• Solutions: A list of HiddenWord structs containing the exact coordinates of placed words.

2. Rendering the Grid

Iterate through the rows and columns to display the board (Unity or Console example).

for (int row = 0; row < board.Size; row++)
{
    for (int col = 0; col < board.Size; col++)
    {
        char c = board.Grid[row, col];
        Console.Write(c + " "); 
    }
    Console.WriteLine();
}

3. Validating a User Move (Swipe)

The SDK includes a helper class PuzzleValidator to check if a user's swipe corresponds to a hidden word.

// 1. Instantiate the Validator
var validator = new PuzzleValidator();

// 2. Capture User Input (Start and End Coordinates)
var start = new Coordinates(0, 0);
var end = new Coordinates(0, 4);

// 3. Check if valid
// Returns the word string (e.g., "UNITY") if found, or null if invalid.
string? foundWord = validator.GetWordIfValid(board, start, end);

if (foundWord != null)
{
    Console.WriteLine($"Success! You found: {foundWord}");
    // Logic to highlight the word and update score...
}
else
{
    Console.WriteLine("Not a valid word.");
}

🛡️ content Filtering (Safety)

If you are loading words from user input or an AI API, you might want to filter out bad words. Implement the IWordFilter interface.

Step 1: Create a Filter

using WordSearch.Core.Interfaces;

public class MySafetyFilter : IWordFilter
{
    private readonly HashSet<string> _bannedWords = new() { "BADWORD", "UGLY" };

    public bool IsSafeWord(string word)
    {
        // Return TRUE if the word is safe to use
        return !_bannedWords.Contains(word.ToUpper());
    }
}

Step 2: Inject into Generator

var filter = new MySafetyFilter();
var generator = new PuzzleGenerator(filter); // Inject filter here

// "BADWORD" will be silently ignored during generation
var board = generator.Generate(new List<string> { "HELLO", "BADWORD" }, 9, 5); 

🎮 Unity Integration Tips

Since GameService.Sdk.WordSearch uses a custom Coordinates struct (to avoid dependency on UnityEngine), you need to map it to Unity's world space.

Example: converting Grid to World Position

public Vector3 GetWorldPosition(int row, int col)
{
    float cellSize = 1.5f; // Space between letters
    float x = col * cellSize;
    float y = -row * cellSize; // Negative because rows go down
    return new Vector3(x, y, 0);
}

🧩 Coordinate System

The SDK uses a 0-based [Row, Col] system.

• [0,0] is Top-Left.
• [0, 8] is Top-Right (in a 9x9 grid).
• [8, 0] is Bottom-Left.

📄 License

This library is licensed under MIT. See the LICENSE file for more details.