PacketNPC

Lightweight packet-based NPC plugin for Paper 1.21+ with zero TPS impact.

A modern alternative to Citizens/FancyNPCs that uses PacketEvents to create server-side NPCs entirely through packets - no real entities, no server performance cost.

---

Features

• Zero TPS Impact - NPCs are packet-only, no real entities on the server
• Per-Player NPCs - Show different NPCs to different players based on permissions or PlaceholderAPI conditions
• Built-in Dialogue System - Branching conversations with clickable options, no external plugin needed
• 12 Action Types - COMMAND, CONSOLE_COMMAND, MESSAGE, SOUND, DIALOGUE, CLOSE, ANIMATION, TITLE, ACTIONBAR, TELEPORT, PARTICLE, POTION
• Multi-Waypoint Patrol - NPCs walk between multiple points with configurable speed, pause, and loop/bounce modes
• Approach/Leave Events - Trigger actions when players approach or leave an NPC
• Custom Skins - Apply any Minecraft player skin (fetched from Mojang API with caching)
• Multiple Entity Types - Player, Villager, Zombie, Skeleton, Iron Golem, and more
• Poses - Standing, Sneaking, Sleeping, Swimming, Dying
• Equipment - Full 6-slot equipment (hand-held item support)
• Head Tracking - NPCs look at the nearest player within range
• Developer API - Full API for other plugins to create and manage NPCs
• PlaceholderAPI Support - Use placeholders in NPC display names
• Fully Configurable - config.yml (20+ settings), messages.yml, npcs.yml, dialogue.yml

Requirements

• Paper 1.21.4+ (or compatible fork)
• PacketEvents 2.7.0+ (Download)
• PlaceholderAPI (optional, for conditions and placeholders)

Installation

1. Download PacketNPC-1.0.0.jar from Releases
2. Place it in your server's plugins/ folder
3. Make sure PacketEvents is also installed
4. Restart the server

Commands

Basic

Command	Description
/npc create <id>	Create NPC at your location
/npc remove <id>	Remove NPC
/npc list	List all NPCs
/npc info <id>	Show detailed NPC info
/npc tp <id>	Teleport to NPC

Appearance

Command	Description
/npc skin <id> <player>	Set skin from player name
/npc name <id> <name>	Set display name (color codes supported)
/npc type <id> <type>	Change entity type (PLAYER, VILLAGER, etc.)
/npc equip <id> <slot> [item]	Set equipment (or use held item)
/npc pose <id> <pose>	Set pose (standing, sneaking, sleeping)
/npc glow <id>	Toggle glowing effect

Behavior

Command	Description
/npc look <id>	Toggle look-at-player
/npc sneak <id>	Toggle crouching
/npc anim <id> <type>	Play animation (swing, hurt, crit)
/npc move <id>	Move NPC to your location

Actions

Command	Description
/npc action <id> <right|left> <type> <value>	Add click action
/npc action <id> list	List all actions
/npc action <id> clear [right|left|all]	Clear actions
/npc action <id> remove <right|left> <index>	Remove specific action

Patrol (Multi-Waypoint)

Command	Description
/npc waypoint <id> add	Add current location as waypoint
/npc waypoint <id> list	List waypoints
/npc waypoint <id> start	Start patrol
/npc waypoint <id> stop	Stop patrol
/npc waypoint <id> speed <value>	Set patrol speed
/npc waypoint <id> pause <ticks>	Set pause duration at each point
/npc waypoint <id> loop	Toggle loop/bounce mode
/npc waypoint <id> clear	Clear all waypoints

Conditions (Per-Player)

Command	Description
/npc perm <id> <permission>	Only visible to players with permission
/npc condition <id> <placeholder> <op> <value>	PlaceholderAPI condition

Admin

Command	Description
/npc reload	Reload all configs
/npc save	Force save NPC data

Configuration

npcs.yml (NPC Definitions)

npcs:
  guard:
    display-name: "&6[Guard] &fKnight"
    type: PLAYER
    skin: "Steve"
    location: { world: world, x: 100.5, y: 64.0, z: 200.5, yaw: 180, pitch: 0 }
    look-at-player: true
    look-range: 15.0
    equipment:
      main-hand: DIAMOND_SWORD
      chestplate: IRON_CHESTPLATE
    actions:
      right-click:
        - type: MESSAGE
          value: "&aWelcome!"
        - type: DIALOGUE
          value: shop_welcome
      on-approach:
        range: 5
        actions:
          - type: MESSAGE
            value: "&7(The guard watches you)"
    patrol:
      enabled: true
      speed: 0.05
      pause: 60
      loop: true
      waypoints:
        - { x: 100, y: 64, z: 200 }
        - { x: 110, y: 64, z: 210 }

dialogue.yml (Dialogue Trees)

dialogues:
  shop_welcome:
    pages:
      - text: "&fHello! How can I help you?"
        options:
          - label: "&aBuy items"
            action: { type: COMMAND, value: "shop open buy" }
          - label: "&eSell items"
            action: { type: COMMAND, value: "shop open sell" }
          - label: "&7Close"
            action: { type: CLOSE, value: "" }

Developer API

PacketNPCAPI api = PacketNPCAPI.getInstance();

// Create NPC
NPC npc = api.createNPC("shop_npc", location);

// Customize
api.setSkin(npc, "Notch");
api.setDisplayName(npc, "&6Shop Keeper");
api.setEquipment(npc, NPC.EquipmentSlot.MAIN_HAND, Material.EMERALD);

// Actions
api.addAction(npc, true, NPCAction.ActionType.COMMAND, "shop open");

// Per-player visibility
api.setPermission(npc, "vip.access");
api.setCondition(npc, "%player_level%", ">=", "10");

// Patrol
api.setPatrol(npc, targetLocation);

// Remove
api.removeNPC("shop_npc");

Permissions

Permission	Default	Description
packetnpc.use	true	Basic NPC interaction
packetnpc.admin	op	NPC creation and management

Why PacketNPC?

Feature	Citizens	FancyNPCs	ZNPCsPlus	PacketNPC
TPS Impact	Heavy (real entities)	Light (NMS)	None (packets)	None (packets)
Per-Player NPCs	No	No	No	Yes
Built-in Dialogue	No (needs Denizen)	No	No	Yes
Maintenance	NMS dependent	NMS per-version modules	PacketEvents	PacketEvents
Approach/Leave Events	No	No	No	Yes
Multi-Waypoint Patrol	Yes (A* pathfinding)	No	No	Yes (linear)
Action Types	Limited	Limited	Limited	12 types

Issues & Feedback

Found a bug or have a suggestion? Please open an issue on the Issues page.

We actively review all reports and appreciate your feedback!

---

PacketNPC (한국어)

Paper 1.21+ 전용 경량 패킷 기반 NPC 플러그인 - 서버 TPS 영향 제로.

Citizens/FancyNPCs의 현대적 대안. PacketEvents를 사용하여 패킷만으로 NPC를 생성합니다 - 실제 엔티티 없음, 서버 성능 비용 없음.

---

주요 기능

• 서버 TPS 영향 0 - NPC는 패킷으로만 존재, 서버에 실제 엔티티 없음
• 퍼플레이어 NPC - 권한/PlaceholderAPI 조건에 따라 플레이어별 다른 NPC 표시
• 대화 시스템 내장 - 분기형 대화 + 클릭 선택지, 별도 플러그인 불필요
• 12개 액션 타입 - 명령어, 메시지, 사운드, 대화, 타이틀, 액션바, 텔레포트, 파티클, 포션 등
• 다중 웨이포인트 순찰 - N개 지점 왕복/순환 + 속도/대기시간 설정
• 접근/이탈 이벤트 - 플레이어가 NPC에 접근하거나 떠날 때 자동 액션
• 커스텀 스킨 - Mojang API에서 자동 로딩 + 캐싱
• 다양한 엔티티 타입 - 플레이어, 주민, 좀비, 스켈레톤, 철 골렘 등
• 포즈 - 서기, 웅크리기, 수면, 수영
• 장비 - 6슬롯 장비 (손에 든 아이템 자동 적용 지원)
• 머리 추적 - 가까운 플레이어를 자동으로 바라봄
• 개발자 API - 다른 플러그인에서 NPC 생성/관리 가능
• PlaceholderAPI 연동 - NPC 이름표에 플레이스홀더 사용
• 완전 커스터마이즈 - config.yml (20개+ 설정), messages.yml, npcs.yml, dialogue.yml

필수 요구사항

• Paper 1.21.4+ (또는 호환 포크)
• PacketEvents 2.7.0+ (다운로드)
• PlaceholderAPI (선택, 조건부 NPC용)

설치

1. Releases에서 PacketNPC-1.0.0.jar 다운로드
2. 서버의 plugins/ 폴더에 넣기
3. PacketEvents도 설치되어 있는지 확인
4. 서버 재시작

버그 신고 / 피드백

버그를 발견하셨거나 건의사항이 있으시면 Issues 페이지에 이슈를 등록해주세요.

모든 신고를 적극적으로 검토하며, 여러분의 피드백을 감사히 받겠습니다!

---

License: MIT