Sample walkthrough

Viewpoint’s source repository has three samples and one legacy model pack. The code on these pages comes from the samples.

Use the samples

1. Build the samples. Run gradlew samples in the source repository. It makes a mod folder for each sample, for example sampleaddon/build/mod/ViewpointSampleAddon.
2. Copy their mod folders into the game’s mods folder.
3. Enable the sample mods and Viewpoint in the game’s mod list.
4. Start the game.
5. Open Advanced, Addons for the sample addon, and Graphics, Resource Packs for the sample resource pack. The samples are in the Inactive column, as all new packages are. The sample Shaderpack is in Graphics, Shaderpacks.
6. Switch them on.

sampleaddon

One addon. It has one small part for each service of the API. Each part is one small class.

• Directorysampleaddon/

  • build.gradle.kts
  • addon.properties
  • settings.properties
  • mod.info
  • CHANGELOG.md
  • Directorymodels/

    • …
  • Directorysounds/

    • …
  • Directorydata/

    • …
  • Directorysrc/main/java/example/sample/

    • SampleAddon.java
    • ViewPart.java
    • and one file for each other part

The classes of an addon cannot be in a package that starts with viewpoint., because Viewpoint reserves it. The sample uses example.sample. It has these parts:

Part	What it does	Page
SampleAddon	Starts the parts. Writes a line to the log when the addon switches on, when its hooks are live, and when it switches off.	Getting started
ViewPart	A ViewListener. Once a second, it writes the eye’s height and the ground height under the crosshair.	View state
SettingsPart	One toggle, two numbers and one key. The key writes a line when you push it. It also adds a settings page, with a button and two value rows.	Settings & keys
FilesPart	Writes a counter with AddonFiles at each enable, and reads it again.	Files
DownloadPart	Asks to download one small file when you click its button on the settings page. The player sees the prompt each time.	Downloads
HookPart	One @Hook.Before hook on a game method. Its handler only reads the call.	Managed patching
ViewpointHookPart	One hook on a listed method of Viewpoint. The render thread calls that method, so the hook has thread = ANY, with a typed handler.	Hooking Viewpoint
ExportPart	Gives one Java function to Lua: Sample.twice(21).	Lua exports
CameraPart	A camera layer that rolls the view a little while the key is down.	Camera layers
ShotPart	A ShotListener that writes the number of hits of each shot.	Aim & shots
DrawPart	A draw callback that draws one small triangle with Gpu, in the top right corner of the screen.	Draw callbacks
SnippetPart	A shader snippet that tints the light at colour.end. While it links, the game pauses.	Shader snippets
ValuesPart	Sets a shader value that the snippet reads.	Shader values
AssetsPart	Writes what its model and its texture take, reads one data file, and loads and plays one sound.	Assets

The descriptor asks only for the permissions that the sample uses. See Permissions.

The card shows the label of the sample. Open the card’s Info. Read Trust, then Permissions, then Hooks. The player reads these tabs before they give consent. Look at them once from the player’s side.

sampleresourcepack

A resource pack, with no code.

• Directorysampleresourcepack/

  • pack.properties
  • mod.info
  • CHANGELOG.md
  • Directorymodels/

    • …
  • Directorytiles/

    • …
  • Directorysounds/

    • …

It has these parts:

• a version 2 manifest with a model on one sprite, a lamp whose shade changes when it is lit, and a chair bound for all its facings by one line;
• a floor and a wall, each with its normal and specular texture;
• one sound, which the card includes. Viewpoint does not play the sounds of a resource pack.

See Format, Model states and Tiles.

sampleshaderpack

A Shaderpack, with no Java.

• Directorysampleshaderpack/

  • pack.properties
  • mod.info
  • CHANGELOG.md
  • Directoryshaders/

    • tint.frag

It builds on the default pack. It adds one option and one pass at the final stage. See Shaderpack format and Passes & inputs.

The legacy model pack

samplelegacypack is a small mod. Its Lua calls Viewpoint.ModelPacks.register, as older model packs do. Viewpoint shows it as the resource pack legacy.ViewpointSampleLegacyPack, with the legacy flag. Its manifest is version 1. It shows that older packs continue to work and follow the player’s order. Do not copy it for a new pack. See Legacy model packs.

Try these changes

1. Increase the sample’s version. Build it again. The card shows a dot. Click Info and open the Changelog tab.
2. Change the line to downloads.hosts=example.com,example.org. The addon now asks for more. It stays off until you give consent again.
3. In Info, Hooks, veto the hook. At the next safe point, the game runs as if the addon has no hook.
4. Drag the sample above or below a different addon. The order in the hook list changes.
5. In Graphics, Shaderpacks, click the green tick on sampleshaderpack. Change its option in Graphics, Shader Options.