Nuke Family Helper Script Development
Development assistant for the Nuke Family faction helper userscript for the online game Torn. This script enhances the game interface with faction management tools including shitlist management, payout distribution, and contract tracking.
What This Skill Does
Provides context-aware assistance when working on the Nuke Family helper userscript, including:
Understanding the dual-file development workflow (dev.user.js + main script)Navigating the codebase architecture (PageType enum, SettingsManager, Observer pattern)Working with the API integration and caching systemsMaintaining TornPDA mobile compatibilityFollowing established patterns for UI injection and stylingPrerequisites
Tampermonkey or similar userscript managerTorn game account with Nuke Family faction leadership permissionsAPI token from nuke.family siteInstructions for AI Agent
When assisting with this project, follow these guidelines:
1. Understand the Development Environment
The project uses a two-file structure: `dev.user.js` (development loader) and `nuke-family-helper.user.js` (main script)`dev.user.js` loads the main script from a local file path using `@require file://...`Debug mode is controlled by `const debug` variable at line 22 of the main scriptTest environment includes both nuke.family and nuke.test domains2. Respect Core Architecture Patterns
**PageType System** (line 234):
Use the PageType enum to identify different game pagesAdd new page types to the enum when extending functionality**SettingsManager** (line 324):
All persistent storage goes through SettingsManagerAPI tokens are stored securely using GM_getValue/GM_setValueBase URL is configurable (production/test environment)**Observer Pattern** (line 745):
Main MutationObserver detects page changesUI injections are triggered by page type detectionAlways clean up observers when no longer needed3. API Integration Standards
Use `GM_xmlhttpRequest` for all API callsInclude Bearer token authentication via SettingsManagerImplement caching with configurable expiration (default 60 minutes)Wrap API calls in try-catch blocks with user-facing error messagesFollow the existing endpoint patterns under base URLKey API endpoints:
`/shit-lists` - Shitlist management`/shit-list-categories` - Category definitions`/user/get-own-roles` - Permission checking`/payout/get-payout-table` - Payout distribution`/contracts/get_contracts` - Contract tracking4. UI Development Guidelines
**Element Creation**:
Use dedicated builder functions for consistent UI componentsAlways prefix custom CSS classes with `nfh-` to avoid game conflictsWait for DOM elements using the `waitForElm()` utility**Styling Convention**:
All custom styles use the `nfh-` namespaceMatch the game's existing visual designEnsure mobile compatibility (TornPDA)5. Data Handling Patterns
**Caching System**:
Use localStorage with timestamp-based expirationImplement cache invalidation when data is staleHandle cache corruption gracefully with try-catch**Async Operations**:
All data fetching is Promise-basedChain operations using async/awaitProvide user feedback during long operations6. Maintain TornPDA Compatibility
The polyfill (lines 32-150) provides GM_* API compatibility for mobileTest changes in both browser and TornPDA environmentsDon't modify the polyfill unless absolutely necessary7. Logging and Debugging
Use `LogInfo()` function with consistent timestamp formattingInclude debug mode checks before verbose loggingLog API responses in debug mode for troubleshooting8. Code Quality Standards
Follow existing naming conventions (camelCase for functions, PascalCase for classes)Add comments for complex logic or API integrationsKeep functions focused and single-purposeDocument new features in code comments9. Testing Checklist
Before committing changes:
Test in both production (nuke.family) and test (nuke.test) environmentsVerify functionality with debug mode enabled and disabledCheck console for errors or warningsTest on different Torn game pages (Profile, Faction, etc.)Verify mobile compatibility if UI changes are made10. Security Considerations
Never hardcode API tokens or credentialsAlways use SettingsManager for sensitive dataValidate user inputs before API callsHandle permission errors gracefullyCommon Tasks
**Adding a new feature**:
1. Determine which PageType(s) it applies to
2. Create data fetching function with caching
3. Build UI injection function with `nfh-` prefixed styles
4. Add observer logic to trigger on appropriate pages
5. Test in debug mode first
**Modifying API integration**:
1. Check SettingsManager for token/URL handling
2. Use existing GM_xmlhttpRequest patterns
3. Implement appropriate caching strategy
4. Add error handling with user feedback
**Updating UI elements**:
1. Use `waitForElm()` for dynamic content
2. Follow `nfh-` CSS naming convention
3. Create builder functions for reusable components
4. Test in both desktop and mobile (TornPDA)
File Structure
`dev.user.js` - Development loader with test environment config`nuke-family-helper.user.js` - Main script with all functionality - Lines 32-150: TornPDA polyfill
- Line 234: PageType enum
- Line 324: SettingsManager class
- Line 745: Main MutationObserver
Constraints
Requires Torn game faction leadership permissionsAPI token must be generated from nuke.family siteScript only functions within Torn game contextMobile support requires TornPDA app