Skip to content

Scoreboards

Jump to bottom
Nick edited this page Dec 20, 2023 · 3 revisions

API History

Module: net.impactdev.impactor.api:scoreboards

Since: 5.2.0

Scoreboard Elements

The following elements detail the individual API components necessary to make a scoreboard with Impactor. Scoreboards flow with the native Minecraft scoreboard design, and are limited to their particular limitations where applicable.

Scoreboard

Represents the basic configuration of a scoreboard that can be viewed by a player. Scoreboards are made up of 3 main components. These components are as follows:

But first, we need to talk about the text that is used to be resolved by these elements...

Scoreboard Components

Scoreboard components represent a general wrapper around Adventure based Components. These elements allow you to do some fun tricks with your overall components, translating any given placeholders dynamically as well as applying transformative effects on the results. The individual components are made up of ComponentElements, which can be appended and transformed as desired. As such, you can have only part of a overall component transformed under a particular text transformer, or have multiple transformers for sections of text.

Let's see an example of a few components, first starting off with one which resolves the ticks per second of a server, while shifting through the visible color spectrum:

ScoreboardComponent tpsComponent = ScoreboardComponent.create(text("TPS: ").color(NamedTextColor.GRAY))
    .append(ComponentElement.create(
        ColorCycle.configure().frames(90).increment(3).build(),
        (viewer, context) -> TextProcessor.mini().parse("<impactor:tps>")
    ));

In this example, we've just created a component that, when updated, will shift through the visible color spectrum over time. We used 90 frames to increase the colors to shift through the text, and instructed how quickly the frames should be run through.

Objective

Objectives represent the grouping element of teams for native Minecraft scoreboards. For this purpose, we will consider them as the title of a scoreboard, acting as the first overall line displayed, with no score.

Objectives are build using a scoreboard resolver, as well as a possible score formatter. Particularly, objectives require the resolver to display content. Use one of the many resolver configurations, or create your own, to update your objective's display as desired.

If a score formatter is configured for an objective, this formatter will apply to all lines that don't have their own formatter specified. As such, you can configure a default renderer for scores to ensure it applies to as many lines as possible, eliminating a decent bit of configuration on the individual lines.

An example of creating an Objective might follow something like this:

Objective objective = Objective.builder()
        .resolver(ScheduledResolverConfiguration.builder()
                .component(ScoreboardComponent.create(text("»").color(NamedTextColor.GRAY).appendSpace())
                        .append(ComponentElement.create(
                                ColorCycle.configure().frames(90).increment(3).build(),
                                (viewer, context) -> text("Impactor Scoreboard Testing")
                        ))
                        .append(space().append(text("«").color(NamedTextColor.GRAY)))
                )
                .scheduler(Schedulers.require(Scheduler.ASYNCHRONOUS))
                .repeating(Ticks.single())
                .build()
        )
        .build();

Scoreboard Line

Lines represent the individual score values associated with a Minecraft team. Lines are sorted on a scoreboard by their score value, with higher values appearing before lower. You'll want to make use of scores to sort your lines as necessary.

Lines, like objectives, use resolvers to control how their content is displayed to the player. Each line can be configured differently, as a means to support dynamic updates. In other words, you can have a static line with never updates past its initial configuration, or a line which updates on a set frequency.

Using our ScoreboardComponent example from earlier, let's see how we could have this built onto a line which updates asynchronously at a normal Minecraft's tick rate:

ScoreboardLine tps = ScoreboardLine.builder()
        .resolver(ScheduledResolverConfiguration.builder()
                .component(tpsComponent)
                .scheduler(Schedulers.require(Scheduler.ASYNCHRONOUS))
                .repeating(Ticks.single())
                .build()
        )
        .score(Score.builder().score(3).build())
        .build();

Scoreboard Renderer

Renderers control how a scoreboard is sent down to the players viewing them. Impactor provides a native capability through packets, but developers are free to design their own methods with this system. Each scoreboard can be configured to use any of these profiles.

Score Formatter

  • NOTE: This component requires Minecraft 1.20.3 or higher. This element provides no other benefit otherwise, and will do nothing if specified on a lower version of Minecraft.

Score formatters control how the score of a particular line displays. By default, scores render in red coloring as a simple number. You can make use of these formatters to hide the score entirely, replace it with another word, re-style it, or do anything custom. The 3 non-custom standards are pre-built into Impactor, so feel free to make use of these at your own pleasure.

Clone this wiki locally