2HoursProject/nexus-timer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

added build-time information

Browse Source
This commit is contained in:
cpu
2025-05-09 23:07:30 +02:00
parent 29d54cdd40
commit 824d977546
10 changed files with 367 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
README.md
View File

@@ -10,20 +10,6 @@ Nexus Timer visualizes players in a circular sequence. The **Current Player** is
Game enthusiasts who play turn-based games (board games, tabletop RPGs, card games) and need a visually clear and customizable timer solution.
## Tech Stack
* **HTML5:** For structuring the user interface.
* **CSS3:** For styling and visual presentation, including animations. Consider a CSS framework like Tailwind CSS for rapid prototyping.
* **JavaScript:** For application logic, timer functionality, and event handling.
* **Web Audio API:** For audio feedback (ticking sounds, alerts).
* **Browser API:** For capturing Players' photo.
* **Screen Wake Lock API:** For preventing of the screen lock in a PWA.
* **Local Storage/IndexedDB:** For persistent storage of player data, timer states, and settings.
* **Service Worker:** Essential for PWA functionality (offline access, push notifications - potential future feature).
* **Manifest File:** Defines the PWA's metadata (name, icons, theme color).
* **Web Framework:** Use Vue.js
* **(Optional) Tailwind CSS:** Utility-first CSS framework for rapid UI development.
## Hardware Recommendations (Optional Enhancement)
For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on Bluetooth-connected microcontroller (e.g., XIAO nRF52840) implementing HID (Human Interface Device) protocol.
@@ -32,10 +18,10 @@ For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on
* **Configuration:**
* **Player 1's Button:** Single Click: Emulates a key press (e.g., 'a'). Configure this as Player 1's "Pass Turn / My Pause" hotkey in the app.
* **Player 2's Button:** Single Click: Emulates a key press (e.g., 'b'). Configure as Player 2's "Pass Turn / My Pause" hotkey.
* If Player 3 is Game Admin:
* **Player 3's Button:** Single Click: Emulates a key press (e.g., 'c'). Configure as Player 3's "Pass Turn / My Pause" hotkey.
* **Player 3's Button:** Double Click: Emulates a key press (e.g., 'x'). Configure as the "Global Run All Timers" hotkey in the app.
* **Player 3's Button:** Long Press: Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.
* **If Player 3 is Game Admin:**
* **Player 3's Button:** Long Press: Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.
* **Player 3's Button:** Double Click: Emulates a key press (e.g., 'x'). Configure as the "Global Run All Timers" hotkey in the app.
## Key Features
@@ -85,7 +71,7 @@ For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on
* **Persistence:** Player setups, timer states, and settings are saved locally using browser Local Storage.
* **Global Reset:** "Reset Game" button restores all timers to initial values and resets game state.
## UI/UX Considerations (For AI Generation)
## UI/UX Considerations
* **Minimalist Design:** Focus on clarity and ease of use. Avoid clutter.
* **Large, Clear Timers:** Timers should be easily readable at a glance.
@@ -93,134 +79,9 @@ For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on
* **Responsive Layout:** The UI should adapt to different (mobile phone) screen sizes.
* **Touch-Friendly:** Buttons and interactive elements should be large enough for easy tapping.
## Data Model (For AI Generation)
### For Developer Setup, see [Developer Setup Guide](docs/development.md).
### For Deployment Setup, see [Deployment Setup Guide](docs/deployment.md).
### For Architecture Docs, see [Architecture](docs/architecture.md).
```json
{
"players": [
{
"id": "1",
"name": "Player 1",
"avatar": null,
"initialTimerSec": 3600,
"currentTimerSec": 3600,
"hotkey": "a",
"isSkipped": false
},
{
"id": "2",
"name": "Player 2",
"avatar": null,
"initialTimerSec": 3600,
"currentTimerSec": 3600,
"hotkey": "b",
"isSkipped": false
}
],
"globalHotkeyStopPause": "s",
"globalHotkeyRunAll": "x",
"currentPlayerIndex": 0,
"gameMode": "normal", // "normal" or "allTimers"
"isMuted": false,
"theme": "dark"
}
```
## Developer Setup
### Clone the repository
```bash
git clone https://gitea.virtonline.eu/2HoursProject/nexus-timer.git
cd nexus-timer
```
Run the live update server locally
```bash
npm run dev
```
### Modify the app
Make code changes...
### Test the PWA locally
Open it in your browser:
[http://localhost:8080/](http://localhost:8080/)
### Git Pre-Commit Hook
This project uses a Git pre-commit hook to automatically updates the build timestamp placeholder in `src/views/InfoView.vue` and increments the `CACHE_VERSION` in `public/service-worker.js` (it is the indicator for the installed PWA that the new version is available). This ensures that each commit intended for a build/deployment reflects the correct information.
#### Configure Git to use the local hooks directory
Tell the Git to use the hooks located in the `.githooks` directory:
```bash
git config core.hooksPath .githooks
```
This step needs to be done once per local clone of the repository. The script `scripts/git-hooks/pre-commit.cjs` will be executed before every commit.
### Commit & Push
Stage changes, commit and push
```bash
git add .
git commit -m 'fixed visuals'
git push
```
## Building for the production
### On the Server
Navigate to the service directory on the server
```bash
cd /virt
```
Clone the repository
```bash
git clone --depth 1 https://gitea.virtonline.eu/2HoursProject/nexus-timer.git
cd nexus-timer
```
Build the docker image
```bash
docker build -t virt-nexus-timer .
```
## Exposing the App Behind Traefik (Reverse Proxy)
### Review the provided docker labels and systemd service file
Copy the example label file to its destination
```bash
cp docker/traefik.labels labels
```
View the example service definition:
```bash
cat systemd/virt-nexus-timer.service
```
### Create the systemd service
Use the editor to create or overwrite the service:
```bash
sudo systemctl edit --force --full virt-nexus-timer.service
```
Paste the content from `systemd/virt-nexus-timer.service`, then save and exit.
Enable on system boot and start the service
```bash
sudo systemctl enable --now virt-nexus-timer.service
```
Check the service status
```bash
systemctl status virt-nexus-timer.service
```
View real-time logs
```bash
journalctl -fu virt-nexus-timer.service
```
### Test the web application
Verify that the application is accessible via HTTPS:
```bash
curl https://nexus-timer.virtonline.eu
```
Or open it in your browser:
[https://nexus-timer.virtonline.eu](https://nexus-timer.virtonline.eu)
## Release the update
### On the Server
Navigate to the app directory on your server
```bash
cd /virt/nexus-timer
```
Pull the changes, build the docker image and restart the service
```bash
git pull && docker build -t virt-nexus-timer . && systemctl restart virt-nexus-timer.service
```
View real-time logs
```bash
journalctl -fu virt-nexus-timer.service
```
The previously installed PWA should update automatically or offer an upgrade