Headless IRC

Published 12/15/2023 Updated 12/19/2023

Zero dependency pure Java library for implementing your own NIO IRC Client / Bot / Crawler / Logger.

What Does It Do?

• Small Java Library that provides an API for maintaining a persistent connection to a specified IRC server.
  • Sending / Receiving message events in groups and private messages
  • Join / Leave Events

Links

• Download Releases
• View Source Code
• Report An Issue

Requirements

• Java 8 or greater

How To Integrate as a Dependency

Clone the repo and import the source with your IDE.

How To Use

1. Create a new bot instance, from there join the server you want and store that object.

IRCBot bot = new IRCBot("YourNickGoesHere", "Java IRC Client");
Server server = bot.join("irc.freenode.net");

2. Using the server object, you can now join channels.

Channel channel1 = server.join("#example-channel-1");
Channel channel2 = server.join("#example-channel-2");

3. Now you can queue messages directly.

channel1.send("Hello channel #1");
channel2.send("Hello channel #2");

How To Use Events

There are three types of event listener: Channel, Server, and Global.

1. Channel message listeners

//handle incoming channel messages
channel1.onMessage(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();
	String msg = event.getMessage();

	if(msg.toLowerCase().contains("hello")) {
		channel.send("Hello, this is a channel message");
		user.send("Hello, this is a private message");
	}
});

//handle channel join updates
channel1.onJoin(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("JOIN: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

//handle channel leave updates
channel1.onLeave(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("QUIT: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

2. Server message listeners

//handle incoming channel messages
server.onChannelMessage(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();
	String msg = event.getMessage();

	if(msg.toLowerCase().contains("hello")) {
		channel.send("Hello, this is a channel message");
		user.send("Hello, this is a private message");
	}
});

//handle incoming private messages
server.onPrivateMessage(event -> {
	User user = event.getUser();
	String msg = event.getMessage();

	if(msg.toLowerCase().contains("hello"))
		user.send("Hello, this is a private message");
});

//handle channel join updates
server.onJoin(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("JOIN: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

//handle channel leave updates
server.onLeave(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("QUIT: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

3. Global message listeners

//handle incoming channel messages
bot.onChannelMessage(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();
	String msg = event.getMessage();

	if(msg.toLowerCase().contains("hello")) {
		channel.send("Hello, this is a channel message");
		user.send("Hello, this is a private message");
	}
});

//handle incoming private messages
bot.onPrivateMessage(event -> {
	User user = event.getUser();
	String msg = event.getMessage();

	if(msg.toLowerCase().contains("hello"))
		user.send("Hello, this is a private message");
});

//handle channel join updates
bot.onJoin(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("JOIN: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

//handle channel leave updates
bot.onLeave(event -> {
	Channel channel = event.getChannel();
	User user = event.getUser();

	System.out.println("QUIT: " + channel.getName() + "[" + channel.getUsers().size() + "] " + user.getNickname());
});

Disclaimer

• Still a work in progress / in development
• Lacks most IRC features beyond the absolute basics

Latest Updates