update.txt

Feature Name: Friend Storage

Overview
- Allows players to add each other as friends and share storage access.
- Friends can use each other's shared storage through a friend-based command system.
- The goal is to make storage collaboration simple, safe, and expandable.

Core Flow
- Player A sends a friend request to Player B.
- Player B accepts the request.
- After becoming friends, both players can access shared storage features with each other.
- Shared access should be mutual by default for the first version.

Recommended Commands
- /storage friends add <player>
- /storage friends accept <player>
- /storage friends deny <player>
- /storage friends remove <player>
- /storage friends list

Best Additions For A More Complete Feature
- Friend request system
  - Prevents instant forced linking.
  - Makes the system safer and more natural for players.

- Basic access control
  - Separate friendship from storage permission internally if possible.
  - Easier to expand later without rewriting the whole system.

- Access modes
  - Mutual access: both players can use each other's storage.
  - This should be the main mode for the first release.

- Activity logs
  - Record who opened storage, deposited items, and withdrew items.
  - Helps resolve disputes and track misuse.

- Emergency revoke / lock
  - Allow players to quickly remove a friend or disable shared access.
  - Useful if trust changes or abuse happens.

- Offline access rule
  - Decide clearly whether a friend can use shared storage while the owner is offline.
  - Recommended: configurable in the future, but keep behavior simple in the first version.

- Friend management GUI
  - Can be added later after command system is stable.
  - Useful for viewing friends, pending requests, and managing shared access.

Recommended Scope For First Release
- Friend requests
- Accept / deny system
- Friend list
- Remove friend
- Mutual shared storage access
- Basic action logging

Future Expansion Ideas
- Per-friend permissions
  - View only
  - Deposit only
  - Withdraw

- Privacy settings
  - Auto deny requests
  - Block specific players
  - Request toggle

- Limits
  - Max number of friends based on permission
  - VIP or rank-based friend slots

- GUI management
  - Friend list GUI
  - Pending request GUI
  - Access settings GUI
  - Logs viewer GUI

Suggested Design Direction
- Keep version 1 simple and command-based.
- Use Friend Storage as the public feature name.
- Build the internal structure so friendship and storage access can be extended later.
- Focus on safety, clarity, and easy future upgrades.

Codebase Integration Notes
- Friend Storage should be implemented as a separate subsystem, not merged directly into MineManager.
- The current project already has a good pattern for feature modules:
  - Storage.java for bootstrap and registration
  - Manager classes for business logic
  - API classes for external access
  - Listeners for session lifecycle
  - message.yml and config files for user-facing content and settings

- Best fit architecture for Friend Storage:
  - Add a dedicated FriendManager
  - Add dedicated Friend Storage API methods
  - Add dedicated friend-related events
  - Add a separate config file for friend settings
  - Add friend messages into message.yml
  - Add permissions into plugin.yml

Core Integration Suggestions
- Storage.java
  - Initialize FriendManager in onEnable()
  - Load or update friend config in File.java setup flow
  - Register any friend listeners if needed
  - Register placeholders related to friends if PlaceholderAPI is enabled
  - Save or flush friend data on shutdown if caching is used

- JoinQuit.java
  - Load friend data when player joins
  - Save friend data when player quits
  - Cleanup friend-related cache or GUI state on quit
  - Optionally notify player of pending friend requests on join

- Command system
  - Add a new subcommand: /storage friends
  - Suggested subcommands:
    - add
    - accept
    - deny
    - remove
    - list
    - open
  - Keep version 1 command-driven first before building GUI

Manager Suggestions
- Add FriendManager as the main business logic layer
- FriendManager responsibilities should include:
  - send friend request
  - accept request
  - deny request
  - remove friend
  - list friends
  - validate shared storage access
  - handle basic logs for shared actions

- Important design note:
  - Do not treat friendship and storage access as exactly the same thing internally
  - Even if version 1 uses accepted friendship = mutual shared storage access
  - The internal structure should still be easy to separate later

API Suggestions
- Add a new FriendStorageAPI
- Suggested methods:
  - sendFriendRequest(player, target)
  - acceptFriendRequest(player, sender)
  - denyFriendRequest(player, sender)
  - removeFriend(player, target)
  - isFriend(playerA, playerB)
  - hasSharedAccess(owner, actor)
  - getFriends(player)
  - getPendingRequests(player)

- Suggested events:
  - FriendRequestSendEvent
  - FriendRequestAcceptEvent
  - FriendRequestDenyEvent
  - FriendRemoveEvent
  - FriendSharedStorageOpenEvent

Listener and GUI Suggestions
- The current GUI system can be reused instead of creating a completely new Friend Storage GUI immediately
- For version 1, it is better to reuse the existing storage viewing flow where possible
- If a friend opens another player's storage, the system should clearly track:
  - storage owner
  - player viewing or interacting
  - action type

- This distinction is important for:
  - logs
  - permissions
  - future access settings
  - preventing incorrect storage operations

Placeholder Suggestions
- Add friend-related placeholders into the existing PAPI expansion
- Suggested placeholders:
  - %storage_friends_count%
  - %storage_friends_pending_count%
  - %storage_friends_access_enabled%

- Keep placeholders simple in version 1
- Avoid complex placeholders that require dynamic target player parsing unless really necessary

Config and Resource Suggestions
- Add a new config file:
  - friendstorage.yml

- Suggested config sections:
  - settings.enabled
  - settings.mutual_access_on_accept
  - settings.allow_offline_access
  - settings.max_friends_default
  - settings.request_expire_seconds
  - settings.notify_on_join
  - settings.log_actions

- Add message.yml sections for:
  - request sent
  - request received
  - request accepted
  - request denied
  - already friends
  - not friends
  - no pending request
  - friend removed
  - shared access denied
  - shared storage opened

- Add plugin.yml permissions for:
  - storage.friends.use
  - storage.friends.add
  - storage.friends.accept
  - storage.friends.deny
  - storage.friends.remove
  - storage.friends.list
  - storage.friends.open

Database and Data Suggestions
- Best option:
  - Store Friend Storage data in separate database tables

- Recommended tables:
  - storage_friends
  - storage_friend_requests
  - storage_friend_logs

- Why this is recommended:
  - easier to maintain
  - easier to expand
  - easier to debug
  - better for logs and permissions

- Not recommended:
  - storing full friend relationship data inside PlayerData.data string format

- Reason:
  - the current string-based storage is acceptable for small toggle data
  - but it becomes difficult to maintain for social relationships, requests, logs, and access states

Important Technical Cautions
- Many current systems are built around the idea that:
  - the player opening storage is also the owner of the storage

- Friend Storage changes that assumption
- The implementation must clearly separate:
  - storage owner
  - actor or viewer

- If this is ignored, likely problems will include:
  - wrong logs
  - wrong permission checks
  - wrong deposit or withdraw target
  - confusing future GUI behavior

- Prefer UUID-based friend relationship storage instead of player name based identity
- Player names can still be used for display, but UUID should be the internal key

Recommended Implementation Scope By Phase
- Phase 1
  - friend requests
  - accept or deny
  - friend list
  - remove friend
  - mutual shared storage access
  - basic action logging
  - command-only workflow

- Phase 2
  - join notifications
  - friend placeholders
  - offline access setting
  - permission-based friend limits

- Phase 3
  - friend GUI
  - pending request GUI
  - per-friend permissions
  - one-way share mode
  - logs viewer GUI

Final Recommendations
- Use Friend Storage as a dedicated access layer on top of the current storage systems
- Reuse current architecture patterns instead of inventing a separate style
- Keep version 1 focused and stable
- Design data structures now so future GUI and permission expansion does not require a rewrite
- Build around owner and actor separation from the beginning

Detailed Plan List

Phase 0 - Design Freeze and Rules
- Define the exact version 1 scope
  - friend request
  - accept
  - deny
  - remove friend
  - list friends
  - mutual shared storage access
  - basic logging

- Decide the default rules
  - accepted friend request = shared storage access
  - access is mutual in version 1
  - offline access allowed or not
  - max friend count default value
  - request expiration behavior

- Define internal terminology before coding
  - owner = owner of the storage
  - actor = player using or opening the storage
  - friend relationship = social link
  - shared access = permission to interact with storage

Phase 1 - Config and Resource Preparation
- Add new resource file
  - src/main/resources/friendstorage.yml

- Add friend config loader support
  - src/main/java/net/danh/storage/Utils/File.java
  - Add build, reload, getter, and updateVersionedConfig support for friendstorage.yml

- Add message keys
  - src/main/resources/message.yml
  - Add messages for:
    - request sent
    - request received
    - request accepted
    - request denied
    - request expired
    - already friends
    - not friends
    - friend removed
    - no pending request
    - cannot add self
    - max friends reached
    - shared access denied
    - shared storage opened
    - friend list header
    - friend list entry
    - no friends

- Add permissions
  - src/main/resources/plugin.yml
  - Add:
    - storage.friends.use
    - storage.friends.add
    - storage.friends.accept
    - storage.friends.deny
    - storage.friends.remove
    - storage.friends.list
    - storage.friends.open

Phase 2 - Data Model and Persistence
- Decide storage approach
  - use separate friend tables
  - do not store full friend data in PlayerData.data

- Add database structures
  - Create friend relationship storage
  - Create pending request storage
  - Create basic friend log storage

- Suggested tables
  - storage_friends
  - storage_friend_requests
  - storage_friend_logs

- Suggested stored fields
  - player_uuid
  - friend_uuid
  - status
  - created_at
  - updated_at
  - request expiry if used
  - log action type
  - owner_uuid
  - actor_uuid

- Add database integration classes
  - src/main/java/net/danh/storage/Database/
  - Add friend-related database wrappers or managers matching the current project style

Phase 3 - Core Manager Implementation
- Add FriendManager
  - src/main/java/net/danh/storage/Manager/Friend/FriendManager.java

- FriendManager should handle:
  - initialization
  - loading online player friend state if caching is used
  - saving player-related state if needed
  - cleanup on quit
  - send request
  - accept request
  - deny request
  - remove friend
  - list friends
  - check if two players are friends
  - check if actor can access owner storage
  - create basic friend action logs

- Keep FriendManager separate from MineManager
- FriendManager should be the gatekeeper for shared access logic

Phase 4 - Core Plugin Integration
- Update plugin bootstrap
  - src/main/java/net/danh/storage/Storage.java

- Add FriendManager initialization in onEnable()
- Add friend config update and load flow
- Add any friend listener registration
- Add friend shutdown or save logic in onDisable()

- Keep integration style consistent with:
  - CropStorageManager
  - MythicStorageManager
  - TransferManager

Phase 5 - Join and Quit Lifecycle
- Update session lifecycle
  - src/main/java/net/danh/storage/Listeners/JoinQuit.java

- On join:
  - load friend data or cache if needed
  - notify pending requests if enabled
  - optionally notify accepted requests received while offline

- On quit:
  - save player-related friend state if caching is used
  - cleanup friend cache
  - cleanup any future GUI state

Phase 6 - Command System
- Add new command handler
  - integrate under /storage friends

- Update command registration
  - src/main/java/net/danh/storage/CMD/CommandManager.java

- Add new command classes or subcommand handlers
  - follow current command architecture style

- Version 1 command checklist
  - /storage friends add <player>
  - /storage friends accept <player>
  - /storage friends deny <player>
  - /storage friends remove <player>
  - /storage friends list
  - /storage friends open <player>

- Command validation rules
  - cannot add self
  - cannot add existing friend
  - cannot send duplicate pending request
  - must have permission
  - must not exceed friend limit
  - target must exist if online-only request system is required

Phase 7 - API Layer
- Add public API for external plugin support
  - src/main/java/net/danh/storage/API/FriendStorageAPI.java

- Add API methods
  - sendFriendRequest
  - acceptFriendRequest
  - denyFriendRequest
  - removeFriend
  - isFriend
  - hasSharedAccess
  - getFriends
  - getPendingRequests

- Keep API naming consistent with:
  - StorageAPI
  - CropStorageAPI
  - MythicStorageAPI

Phase 8 - Event Layer
- Add friend-related Bukkit events
  - src/main/java/net/danh/storage/API/events/

- Version 1 recommended events
  - FriendRequestSendEvent
  - FriendRequestAcceptEvent
  - FriendRequestDenyEvent
  - FriendRemoveEvent
  - FriendSharedStorageOpenEvent

- Event design rules
  - make action events cancellable where useful
  - include owner and actor if the event is about shared storage access
  - include old and new state if future permission toggles are added

Phase 9 - Shared Storage Access Integration
- Reuse the current storage GUI flow where possible
- Do not create a large new GUI system in version 1 unless needed

- Main implementation goal
  - allow actor to open owner storage only if FriendManager allows it

- Important implementation rule
  - do not assume the player interacting is the owner of the storage

- Review affected areas
  - view/open storage flow
  - deposit flow
  - withdraw flow
  - sell flow if shared selling is allowed in the future
  - transfer or history systems if they later integrate with friend access

- Add logging whenever a friend:
  - opens storage
  - deposits items
  - withdraws items

Phase 10 - Placeholder Integration
- Update PlaceholderAPI expansion
  - src/main/java/net/danh/storage/Placeholder/PAPI.java

- Add simple version 1 placeholders
  - %storage_friends_count%
  - %storage_friends_pending_count%
  - %storage_friends_access_enabled%

- Keep version 1 placeholders simple and stable

Phase 11 - Validation and Edge Cases
- Test friend request edge cases
  - request self
  - request same player twice
  - accept non-existing request
  - deny non-existing request
  - remove non-friend
  - max friend limit reached

- Test shared storage edge cases
  - open friend storage with no access
  - owner offline if offline access disabled
  - stale request data
  - target name changed but UUID remains valid

- Test lifecycle edge cases
  - join with pending requests
  - quit during request flow
  - plugin reload with online players
  - server shutdown save path

Phase 12 - Future Expansion Preparation
- Prepare for version 2 without rewriting version 1
- Leave internal hooks for:
  - one-way share mode
  - per-friend permissions
  - GUI friend manager
  - friend request GUI
  - detailed access logs
  - log viewer GUI

Practical Build Order
- Step 1
  - add friendstorage.yml
  - add message.yml keys
  - add plugin.yml permissions

- Step 2
  - create database structures
  - create FriendManager

- Step 3
  - wire FriendManager into Storage.java and JoinQuit.java

- Step 4
  - add /storage friends commands

- Step 5
  - add FriendStorageAPI and events

- Step 6
  - integrate shared storage opening and basic logs

- Step 7
  - add placeholders

- Step 8
  - test edge cases and cleanup behavior