Documentation for Battleground.js

Overview

Battleground.js is a web application designed to simulate and visualize unit movements on a map. It provides tools for managing fields, units, and their histories, with a focus on real-time updates and user interaction.

---

Installation

To set up the project, follow these steps:

1. Clone the repository.

2. Install dependencies using pnpm:

   pnpm i

3. Generate the back-end Prisma client:

   pnpm p:generate

---

Running the Application

To start the application, use the following commands:

1. Start the development server:

   pnpm dev

2. Simulate unit movement (e.g., for a unit named "Tank"):

   pnpm simulate

---

Project Structure

Key Directories and Files

• /app/home/fields: Contains pages for managing fields.

  • page.tsx: Displays a list of fields.
  • new/page.tsx: Allows users to add new fields.

• /app/home/map: Contains the main map page.

  • page.tsx: Displays the map with fields, units, and their histories.

• /app/home/units: Contains pages for managing units.

  • page.tsx: Displays a list of units.

• /lib/api: Contains server-side functions for interacting with the database.

  • getFields.ts: Fetches all fields.
  • getUnits.ts: Fetches all units.
  • getUnitHistory.ts: Fetches the history of a specific unit.
  • addUnitHistory.ts: Adds a new entry to a unit's history.

• /lib/components: Contains reusable React components.

  • BtMainMap.tsx: The main map component.
  • BtUnitCard.tsx: Displays information about a unit.
  • BtDateRange.tsx: A date range picker component.

• /generated/prisma: Contains TypeScript types generated by Prisma.

• /prisma: Contains Prisma schema and configuration files.

---

Key Features

Fields Management

• View a list of fields on the /home/fields page.
• Add new fields using the /home/fields/new page, which includes:
  • A form for entering field details (name, type, start and end dates).
  • A map picker for selecting field positions.

Units Management

• View a list of units on the /home/units page.
• Each unit card displays:
  • Unit name and speed.
  • A map showing the unit's movement history.

Map Visualization

• The /home/map page displays:
  • Fields and units on a map.
  • Real-time updates via WebSocket for unit movements.
  • Focus on specific fields or units using query parameters (focusOnField or focusOnUnit).

Real-Time Updates

• WebSocket integration allows real-time updates for unit movements.
• New positions are saved to the database and reflected on the map.

---

Development

Linting

Run the linter to ensure code quality:

pnpm lint

Prisma Commands

• Open Prisma Studio to manage the database:

  pnpm p:studio

• Apply database migrations:

  pnpm p:migrate

---

Dependencies

Major Dependencies

• React: Front-end library for building user interfaces.
• Next.js: Framework for server-side rendering and routing.
• Prisma: ORM for database management.
• Leaflet: Library for interactive maps.
• MUI: Material-UI components for styling.

Key Packages

• @emotion/react and @emotion/styled: For styling components.
• dayjs: For date and time manipulation.
• @prisma/client: Prisma client for database queries.

---

Environment Variables

Ensure the following environment variables are set in a .env file:

• DATABASE_URL: Connection string for the database.
• NEXT_PUBLIC_WEBSOCKET_URL: URL for the WebSocket server.

---

Contributing

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Submit a pull request with a detailed description of your changes.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.