[bc break!!!] API improvements and documentation improvements #3

DaisukeDaisuke · 2025-07-16T03:53:31Z

new APIs

We no longer have to type libcamera::getPresetRegistry()->registered every time

preset: libcamera::getPresetRegistry()->registered["free"]

With the new API it looks like this:

preset: CameraPresetRegistry::FREE(),

Want to use a preset from a string? Use match()

		$string = "free";
		$preset = match(strtolower($string)){
			"free" => CameraPresetRegistry::FREE(),
			"first_person" => CameraPresetRegistry::FIRST_PERSON(),
			"third_person" => CameraPresetRegistry::THIRD_PERSON(),
			"third_person_front" => CameraPresetRegistry::THIRD_PERSON_FRONT(),
			"target" => CameraPresetRegistry::TARGET(),
			default => null,
		};

Want to use a preset with partial matches? Use str_start_with()

	public function getPreset(string $str) : ?CameraPreset{
		$string = strtolower($str);
		if(str_starts_with("free", $string)){
			return CameraPresetRegistry::FREE();
		}else if(str_starts_with("first", $string)){
			return CameraPresetRegistry::FIRST_PERSON();
		}else if(str_starts_with("third", $string)){
			return CameraPresetRegistry::THIRD_PERSON();
		}else if(str_starts_with("third_front", $string)){
			return CameraPresetRegistry::THIRD_PERSON_FRONT();
		}else if(str_starts_with("target", $string)){
			return CameraPresetRegistry::TARGET();
		}
		return null;
	}

The following functions have been added:

libcamera::registerPreset();
libcamera::newId();

The following functions have been removed:

libcamera::getPresetRegistry()

New exceptions added

[00:21:15.207] [Server thread/INFO]: [libcamera] WARNING: libcamera is not registered.
[00:21:15.207] [Server thread/INFO]: [libcamera] You must call libcamera::register($plugin) before using any camera instructions.
[00:21:15.207] [Server thread/INFO]: [libcamera] Example:
[00:21:15.207] [Server thread/INFO]: [libcamera] public function onEnable() : void{
[00:21:15.207] [Server thread/INFO]: [libcamera]     if(!AwaitForm::isRegistered()){ 
[00:21:15.208] [Server thread/INFO]: [libcamera]         AwaitForm::register($this);
[00:21:15.208] [Server thread/INFO]: [libcamera]      }
[00:21:15.208] [Server thread/INFO]: [libcamera] }
[00:21:15.208] [Server thread/EMERGENCY]: Crash occurred while handling a packet from session:
[00:21:15.209] [Server thread/CRITICAL]: RuntimeException: "libcamera::register() must be called before using CameraInstruction::set()" (EXCEPTION) in "plugins/libcamera/src/muqsit/libcamera/CameraInstruction" at line 51

Improved readme

Added documentation with various tested use cases and videos

Linked Issues

closed #2

About Squash Merge

I am committing with the assumption that it will be squash-merged, so please squash-merge.

inxomnyaa · 2025-08-05T11:42:03Z

This PR is doing way too many things at once. Please split the PR into individual parts (just like PRs at the PocketMine-MP repo.. it's simply too noisy and prone to errors)

inxomnyaa · 2025-08-05T11:44:52Z

Also, if i read this correctly, this stops custom presets from being used - though i am not 100% sure these worked anyways without modifying the source code of the repo 🤷🏻‍♂️

inxomnyaa · 2025-08-05T11:47:10Z

README.md

 		rot: new CameraSetInstructionRotation(
-			(float)20.0, //pitch
-			(float)180.0 //yaw
+			(float)20, //pitch


unnecessary change which will make phpstorm and probably phpstan complain (also inconsistent with other occurrences of floating point numbers, see line 84 for example)

inxomnyaa · 2025-08-05T11:47:59Z

README.md

 			(float) 5.0 // duration (sec)
 		),
-		camera_pos: null,
+		camera_pos: $player->getPosition()->add(0.0, $player->getEyeHeight(), 0.0), //Without it, the camera will teleport into subspace


i am quite certain this is nullable, it uses the previous/current position

I actually test everything
I think it means that once you specify it, it can be null, but in this case, since there is only one specification, it is not possible to specify null

m11.mp4

inxomnyaa · 2025-08-05T11:51:07Z

README.md


+After setting the camera to free mode, you need to explicitly assign a target.  
+This allows the camera to visually track a specific entity.  
+Unlike SetActorLinkPacket, it does not follow the entity automatically.  


This sentence is simply confusing. It does follow the entity automatically, you just have to instruct it correctly

Perhaps I should clarify that it is perspective tracking

inxomnyaa · 2025-08-05T11:54:11Z

README.md

+
+		//Manages which packets have been sent
+		$this->set[$player->getName()] = true;
+	}


Not only is this absolute overkill, you also seem to have misunderstood how the instructions send the packets - this, as far as i remember, is automatically handled on send

I would need to unlock it with a sneak click, start it with a normal click, or unlock it over time

inxomnyaa · 2025-08-05T11:55:15Z

README.md

 - Multi

+This doesn't work
+


could be my fault, some of the recent changes before upload were a bit sus - but we don't have to mention it in the readme. create an issue.

inxomnyaa · 2025-08-05T11:56:07Z

README.md

+- registerCustom Preset
+
+First, build a custom preset registry
+CustomCameraPresetRegistry.php


This should be provided by the virion

Having an actual implementation of an abstract class reduces the code load

inxomnyaa · 2025-08-05T11:57:50Z

README.md

+use pocketmine\scheduler\ClosureTask;
+use pocketmine\entity\Zombie;
+use muqsit\libcamera\CameraPresetRegistry;
+```


what is this block of use statements? this bloats the README for no real gain. These are also handled by the IDE usually.

inxomnyaa · 2025-08-05T12:01:26Z

README.md

+| out_sine       | Decelerates toward the endpoint                                | [see](#out_sine-demo)       | ❌       |
+| in_out_sine    | Combines both in and out sine behaviors                        | [see](#in_out_sine-demo)    | ❌       |
+| linear         | Moves from start to end at constant speed                      | [see](#linear-demo)         | ❌       |
+| spring         | Slightly oscillates around the endpoint                        | [see](#spring-demo)         | ✅       |


Easing types are a widely known concept, also they are already mentioned in the bedrock docs (which are linked in the beginning)
This is simply too maintenance heavy to keep in the README, and its overwhelming and unnecessary information for the average user. This readme is about using the virion to enable the cameras, not to explain the whole system itself. Those things should be handled by wikis if anything.

inxomnyaa · 2025-08-05T12:02:30Z

README.md

+		if(!$player->isSneaking()){
+			return;
+		}
+		if($player instanceof Player&&$player->isOnline()){


formatting - or just yeet it all

inxomnyaa · 2025-08-05T12:04:28Z

This is just way too much useless bloat and information in the README. I don't have the time, will or energy to review these unnecessary changes. Debloat, then request another review please.

DaisukeDaisuke · 2025-08-05T23:18:50Z

This is a duct-tape API improvement created for use on my server(ver 1.21.93), so I no longer intend to have it merged, but I will respond to this review to some extent

DaisukeDaisuke added 29 commits July 15, 2025 14:25

fix for 1.21.93

84f8be2

update README.md

263e5eb

update README.md

a2503e8

Our new API

8065b87

remove var_dumo

64cd8dd

Update README.md

0b340db

Update README.md

456456d

Update README.md

f0b17cb

Update README.md

c65f841

Update README.md

010adb1

Update README.md

1fa4d87

Update README.md

252a90b

Update README.md

edd86df

Update README.md

3c99f0d

Update README.md

1d30540

Update README.md

f430938

Update README.md

d507862

Update README.md

710e149

Update README.md

9aac2a3

Update README.md

f99fea4

Update README.md

5e156f3

update README.md

67579a0

not plugin

cbfc227

private static function newId()

ff6dae5

fixbug in README.md

9535029

WARNING: libcamera is not registered

822e1c6

fix

b400707

fixPrefixedLogger

a8579dc

fix typo

d1d0dac

DaisukeDaisuke marked this pull request as ready for review July 18, 2025 23:34

inxomnyaa reviewed Aug 5, 2025

View reviewed changes

[bc break!!!] API improvements and documentation improvements #3

Are you sure you want to change the base?

[bc break!!!] API improvements and documentation improvements #3

Uh oh!

Conversation

DaisukeDaisuke commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

new APIs

The following functions have been added:

The following functions have been removed:

New exceptions added

Improved readme

Linked Issues

About Squash Merge

Uh oh!

inxomnyaa commented Aug 5, 2025

Uh oh!

inxomnyaa commented Aug 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DaisukeDaisuke Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

inxomnyaa commented Aug 5, 2025

Uh oh!

DaisukeDaisuke commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DaisukeDaisuke commented Jul 16, 2025 •

edited

Loading

DaisukeDaisuke Aug 6, 2025 •

edited

Loading

DaisukeDaisuke commented Aug 5, 2025 •

edited

Loading