# HytaleJS HytaleJS lets you write Hytale server plugins in TypeScript. Get full type safety, autocomplete, and a familiar development experience. ## Features Write plugins with full type safety and IDE autocomplete Listen to player joins, chat, block breaks, and 30+ events Register custom commands with permissions Run delayed and repeating tasks ## Quick Example ```typescript import { EventListener, Colors } from "@hytalejs.com/core"; class MyPlugin { @EventListener("PlayerConnectEvent") onJoin(event: PlayerConnectEvent) { const player = event.getPlayer(); player.sendMessage( Message.raw("Welcome!").color(Colors.GREEN).bold(true) ); } } commands.register("hello", "Say hello", (ctx) => { ctx.sendMessage("Hello, " + ctx.getSenderName() + "!"); }); ``` ## Getting Started Set up your development environment Build a complete plugin step by step Explore all available types and methods # Your First Plugin import { Step, Steps } from 'fumadocs-ui/components/steps'; Let's build a plugin that welcomes players, formats chat, and adds a `/players` command. ### Create src/main.ts ```typescript import { type PlayerConnectEvent, type PlayerChatEvent, EventListener, Colors } from "@hytalejs.com/core"; ``` ### Add a welcome message on join ```typescript class MyPlugin { @EventListener("PlayerConnectEvent") onJoin(event: PlayerConnectEvent) { const player = event.getPlayer(); const name = event.getPlayerRef().getUsername(); player.sendMessage( Message.raw("Welcome, " + name + "!").color(Colors.GREEN).bold(true) ); Universe.get().sendMessage( Message.raw(name + " joined the server!") ); } } ``` ### Format chat messages ```typescript @EventListener("PlayerChatEvent") onChat(event: PlayerChatEvent) { const sender = event.getSender(); const content = event.getContent(); const formatted = Message.empty() .insert(Message.raw(sender.getUsername()).color(Colors.GOLD).bold(true)) .insert(Message.raw(": ").color(Colors.GRAY)) .insert(Message.raw(content).color(Colors.WHITE)); event.setCancelled(true); const targets = event.getTargets(); for (let i = 0; i < targets.length; i++) { targets[i].sendMessage(formatted); } } ``` ### Register a command ```typescript commands.register("players", "List online players", (ctx) => { const universe = Universe.get(); ctx.sendMessage("Online: " + universe.getPlayerCount()); const players = universe.getPlayers(); for (let i = 0; i < players.length; i++) { ctx.sendMessage("- " + players[i].getUsername()); } }); ``` ### Build and deploy ```bash npm run build cp dist/plugin.js /path/to/hytale-server/mods/bmstefanski_HytaleJS/scripts/ ``` Restart your server to load the plugin. ## Complete Code ```typescript import { type PlayerConnectEvent, type PlayerChatEvent, EventListener, Colors } from "@hytalejs.com/core"; class MyPlugin { @EventListener("PlayerConnectEvent") onJoin(event: PlayerConnectEvent) { const player = event.getPlayer(); const name = event.getPlayerRef().getUsername(); player.sendMessage( Message.raw("Welcome, " + name + "!").color(Colors.GREEN).bold(true) ); Universe.get().sendMessage(Message.raw(name + " joined the server!")); } @EventListener("PlayerChatEvent") onChat(event: PlayerChatEvent) { const sender = event.getSender(); const content = event.getContent(); const formatted = Message.empty() .insert(Message.raw(sender.getUsername()).color(Colors.GOLD).bold(true)) .insert(Message.raw(": ").color(Colors.GRAY)) .insert(Message.raw(content).color(Colors.WHITE)); event.setCancelled(true); const targets = event.getTargets(); for (let i = 0; i < targets.length; i++) { targets[i].sendMessage(formatted); } } } commands.register("players", "List online players", (ctx) => { const universe = Universe.get(); ctx.sendMessage("Online: " + universe.getPlayerCount()); const players = universe.getPlayers(); for (let i = 0; i < players.length; i++) { ctx.sendMessage("- " + players[i].getUsername()); } }); ``` ## Next Steps Learn about all available events Add permissions and parse arguments # Installation import { Step, Steps } from 'fumadocs-ui/components/steps'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; import { Callout } from 'fumadocs-ui/components/callout'; ## Server Setup ### Download HytaleJS Download the latest `HytaleJS.jar` from the [releases page](https://github.com/bmstefanski/HytaleJS/releases). ### Install the plugin Copy `HytaleJS.jar` to your Hytale server's mods folder: ``` hytale-server/mods/HytaleJS.jar ``` ### Start your server The plugin will create a scripts folder at: ``` hytale-server/mods/bmstefanski_HytaleJS/scripts/ ``` All `.js` files in the scripts folder are automatically loaded when the server starts. ## Development Setup To write plugins in TypeScript with type checking and autocompletion: ### Prerequisites * Node.js 18+ ### Setup ### Create a new project ```bash mkdir my-plugin && cd my-plugin npm init -y ``` ### Install dependencies ```bash pnpm add @hytalejs.com/core pnpm add -D typescript esbuild ``` ```bash npm install @hytalejs.com/core npm install -D typescript esbuild ``` ```bash bun add @hytalejs.com/core bun add -D typescript esbuild ``` ### Create tsconfig.json ```json { "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "noEmit": true, "experimentalDecorators": true, "types": ["@hytalejs.com/core"] }, "include": ["src"] } ``` ### Add build script to package.json ```json { "scripts": { "build": "esbuild src/main.ts --bundle --format=esm --target=es2022 --outfile=dist/plugin.js" } } ``` ## Project Structure ``` my-plugin/ ├── src/ │ └── main.ts # Your plugin code ├── dist/ │ └── plugin.js # Built output (deploy this) ├── package.json └── tsconfig.json ``` ## Deploying Copy your built `dist/plugin.js` to the HytaleJS scripts folder: ``` hytale-server/mods/bmstefanski_HytaleJS/scripts/plugin.js ``` Restart your server to load the plugin. ## Next Steps Build a complete plugin with events and commands # API Reference This page contains auto-generated documentation for all 695 HytaleJS types, sorted alphabetically. ## A ### AOECircleSelector ### AOECylinderSelector ### AbilityEffects ### AccessControlModule ### ActiveAnimationComponent ### ActiveEntityEffect ### AddItemInteraction ### AddPlayerToWorldEvent ### AliveCondition ### AllLegacyEntityTypesQuery ### AllLegacyLivingEntityTypesQuery ### Anchor ### AnimationUtils ### ApplicationEffects ### ApplyEffectInteraction ### ApplyForceInteraction ### ApplyRandomSkinPersistedComponent ### Area ### AssetStore ### AudioComponent ### AudioSystems ## B ### BanCommand ### BasicCollisionData ### BinaryPrefabBufferCodec ### BlockCollisionData ### BlockCollisionProvider ### BlockConditionInteraction ### BlockContactData ### BlockCounter ### BlockData ### BlockDataProvider ### BlockEntity ### BlockEntitySystems ### BlockFilter ### BlockHarvestUtils ### BlockHealth ### BlockHealthChunk ### BlockHealthModule ### BlockIdMatcher ### BlockInteractionUtils ### BlockMask ### BlockMaskConstants ### BlockMatcher ### BlockMigrationExtraInfo ### BlockModule ### BlockPattern ### BlockPlaceUtils ### BlockSetCommand ### BlockSetLookupTable ### BlockSetModule ### BlockState ### BlockTracker ### BlockType ### BodyType ### BootEvent ### BoundingBox ### Box ### BoxBlockIntersectionEvaluator ### BoxCollisionData ### BreakBlockEvent ### BreakBlockInteraction ### BsonPrefabBufferDeserializer ### BuilderToolInteraction ### ByteArrayCommonAsset ### ByteArrayCommonAssetStatic ## C ### CalculationResult ### CameraInteraction ### CameraManager ### CancelChainInteraction ### ChainFlagInteraction ### ChainingInteraction ### ChangeActiveSlotInteraction ### ChangeBlockInteraction ### ChangeGameModeEvent ### ChangeStatInteraction ### ChangeStatWithModifierInteraction ### ChangeStateInteraction ### CharacterCollisionData ### ChargingCondition ### ChargingInteraction ### CheckUniqueItemUsageInteraction ### ChunkLightingManager ### ChunkTracker ### ChunkUtil ### ClearEntityEffectInteraction ### ClientDelegatingProvider ### ClientReferral ### ClientSourcedSelector ### CollisionConfig ### CollisionDataArray ### CollisionMaterial ### CollisionMath ### CollisionModule ### CollisionModuleConfig ### CollisionResult ### CollisionResultComponent ### CollisionTracker ### Color ### ColorLight ### CombatTextUIComponent ### CombatTextUIComponentOpacityAnimationEvent ### CombatTextUIComponentPositionAnimationEvent ### CombatTextUIComponentScaleAnimationEvent ### CommandContext ### CommandSender ### CommonAsset ### CommonAssetModule ### CommonAssetModuleStatic ### ComponentAccessor ### ComponentType ### ConditionInteraction ### ContainerBlockWindow ### ContainerWindow ### CooldownConditionInteraction ### CooldownHandler ### CosmeticAssetValidator ### CosmeticRegistry ### CosmeticType ### CosmeticsModule ### CraftRecipeEvent ### CraftingRecipe ### CraftingRecipePacketGenerator ### CustomHud ### CustomPage ### CustomPageLifetime ### CustomPageLifetimeEnum ### CustomUICommand ### CustomUICommandType ### CustomUICommandTypeEnum ### CustomUIEventBinding ### CustomUIEventBindingType ### CustomUIEventBindingTypeEnum ### CustomUIHud ### CustomUIPage ### CycleBlockGroupInteraction ### Cylinder ## D ### DamageBlockEvent ### DamageCalculator ### DamageCalculatorSystems ### DamageCause ### DamageClass ### DamageDataComponent ### DamageDataSetupSystem ### DamageEffects ### DamageEntityInteraction ### DamageModule ### DamageSystems ### DeathComponent ### DeathItemLoss ### DeathSystems ### DebugCommand ### DebugPlugin ### DebugShapeArrowCommand ### DebugShapeClearCommand ### DebugShapeConeCommand ### DebugShapeCubeCommand ### DebugShapeCylinderCommand ### DebugShapeShowForceCommand ### DebugShapeSphereCommand ### DebugShapeSubCommand ### DebugUtils ### DefaultAssetMap ### DeferredCorpseRemoval ### DespawnComponent ### DespawnSystem ### DestroyBlockInteraction ### DestroyConditionInteraction ### DesyncDamageCommand ### Direction ### DirectionalKnockback ### DisconnectReason ### DiscoverZoneEvent ### DisplayNameComponent ### DoorInteraction ### DrainPlayerFromWorldEvent ### DropItemEvent ### DropdownEntryInfo ### DynamicLight ### DynamicLightSystems ## E ### EffectConditionInteraction ### EffectControllerComponent ### Emote ### EmoteCommand ### EnableTmpTagsCommand ### Entity ### EntityCleanCommand ### EntityCloneCommand ### EntityCollisionProvider ### EntityCommand ### EntityContactData ### EntityCountCommand ### EntityDumpCommand ### EntityEffect ### EntityEffectCommand ### EntityEffectPacketGenerator ### EntityEvent ### EntityGroup ### EntityHideFromAdventurePlayersCommand ### EntityIntangibleCommand ### EntityInteractableSystems ### EntityInvulnerableCommand ### EntityLodCommand ### EntityMakeInteractableCommand ### EntityModule ### EntityNameplateCommand ### EntityRefCollisionProvider ### EntityRegistration ### EntityRegistry ### EntityRemoveCommand ### EntityRemoveEvent ### EntityResendCommand ### EntityScaleComponent ### EntitySnapshot ### EntitySnapshotHistoryCommand ### EntitySnapshotLengthCommand ### EntitySnapshotSubCommand ### EntitySpatialSystem ### EntityStatMap ### EntityStatType ### EntityStatTypePacketGenerator ### EntityStatUIComponent ### EntityStatValue ### EntityStatsAddCommand ### EntityStatsDumpCommand ### EntityStatsGetCommand ### EntityStatsResetCommand ### EntityStatsSetCommand ### EntityStatsSetToMaxCommand ### EntityStatsSubCommand ### EntityStore ### EntitySystems ### EntityTrackerCommand ### EntityTrackerSystems ### EntityUIComponentPacketGenerator ### EntityUIModule ### EntityUtils ### EnvironmentCondition ### EquipItemInteraction ### EventData ### EventDataStatic ### EventHandler ### EventType ### ExplodeInteraction ### ExplosionConfig ### ExplosionUtils ## F ### FirstClickInteraction ### FloodLightCalculation ### FluidIterator ### FlyCameraModule ### ForceAccumulator ### ForceKnockback ### ForceProviderEntity ### ForceProviderStandardState ### Formatter ### FragileBlock ### FromPrefab ### FromWorldGen ### Frozen ### FullBrightLightCalculation ## G ### GameMode ### GenerateDefaultLanguageEvent ### GenerateI18nCommand ### GenericVelocityInstructionSystem ### GlidingCondition ### GroupPermissionChangeEvent ## H ### HeadRotation ### HexColor ### HiddenFromAdventurePlayers ### HiddenPlayersManager ### HideEntitySystems ### HitboxCollision ### HitboxCollisionConfig ### HitboxCollisionConfigPacketGenerator ### HitboxCollisionSystems ### HitboxCommand ### Holder ### HorizontalSelector ### HostAddress ### HotbarManager ### HudComponent ### HudComponentEnum ### HudManager ### HytaleBanProvider ### HytaleServerInstance ### HytaleServerStatic ### HytaleWhitelistProvider ## I ### I18nModule ### IncreaseBackpackCapacityInteraction ### IncrementCooldownInteraction ### IndexedAssetMap ### InfiniteBan ### InputUpdate ### Intangible ### IntangibleSystems ### Interactable ### InteractionCameraSettings ### InteractionChain ### InteractionClearCommand ### InteractionCommand ### InteractionConfiguration ### InteractionContext ### InteractionEffects ### InteractionEntry ### InteractionManager ### InteractionModule ### InteractionPacketGenerator ### InteractionPriorityCodec ### InteractionRules ### InteractionRunCommand ### InteractionRunSpecificCommand ### InteractionSetSnapshotSourceCommand ### InteractionSimulationHandler ### InteractionSnapshotSourceCommand ### InteractionSystems ### InteractionTarget ### InteractionType ### InteractionTypeUtils ### Interactions ### InteractivelyPickupItemEvent ### InternationalizationCommands ### InterruptInteraction ### InvalidatablePersistentRef ### Inventory ### Invulnerable ### InvulnerableSystems ### Item ### ItemClass ### ItemComponent ### ItemContainer ### ItemContainerStateSpatialSystem ### ItemGridSlot ### ItemMergeSystem ### ItemModule ### ItemPacketGenerator ### ItemPhysicsComponent ### ItemPhysicsSystem ### ItemPrePhysicsSystem ### ItemQualityPacketGenerator ### ItemRepairElement ### ItemRepairPage ### ItemRepairPageSupplier ### ItemReticleConfigPacketGenerator ### ItemSpatialSystem ### ItemStack ### ItemStackContainerWindow ### ItemStackSlotTransaction ### ItemStackTransaction ### ItemSystems ### ItemUtils ## J ### JavaByteArray ### JavaByteClass ### JavaClass ### JavaCompletableFuture ### JavaInterop ### JavaIterator ### JavaList ### JavaMap ### JavaSet ### JavetCallMetrics ### JumpOperation ## K ### KillFeedEvent ### KnockbackComponent ### KnockbackPredictionSystems ### KnockbackSimulation ### KnockbackSystems ## L ### Label ### LangFileParser ### LaunchPadInteraction ### LaunchProjectileInteraction ### LegacyEntityTrackerSystems ### LegacyModule ### LegacyProjectileSystems ### ListCollector ### LivingEntityEffectClearChangesSystem ### LivingEntityEffectSystem ### LivingEntityInventoryChangeEvent ### LivingEntityUseBlockEvent ### LocalizableString ### LogicCondition ## M ### MaterialExtraResourcesSection ### MaterialQuantity ### Message ### MessageStatic ### MessagesUpdated ### MigrationModule ### ModelComponent ### ModelOverride ### ModelSystems ### ModelTransform ### ModifyInventoryInteraction ### MouseButtonEvent ### MouseMotionEvent ### MovementAudioComponent ### MovementConditionInteraction ### MovementConfig ### MovementManager ### MovementStatesComponent ### MovementStatesSystems ### MovingBoxBoxCollisionEvaluator ### MultiBlockMask ## N ### NameMatching